moflo 4.9.10 → 4.9.11

package/.claude/guidance/shipped/moflo-spell-engine.md

@@ -122,7 +122,7 @@ steps:
 
 ## Step Command Types
 
-**Nine built-in step types are registered automatically.** Each implements `execute()`, `validate()`, `describeOutputs()`, and optional `rollback()`. Additional step types can be added via [pluggable step discovery](#pluggable-step-commands).
+**Nine built-in step types are registered automatically.** Each implements `execute()`, `validate()`, `describeOutputs()`, and optional `rollback()`. Additional step types can be added via pluggable step discovery — see `moflo-spell-custom-steps.md` for the JS/TS, YAML, and npm-package extension paths.
 
 ### bash — Run a Shell Command
 
@@ -276,107 +276,9 @@ Supports 8 actions: `create-issue`, `create-pr`, `add-label`, `remove-label`, `c
 
 ---
 
-## Pluggable Step Commands
-
-**Drop JS/TS or YAML files into a step directory to extend the spell engine with custom step types.** User-defined steps are auto-discovered and registered alongside built-in commands.
-
-### Discovery Sources (Priority Order)
-
-| Priority | Source | Path |
-|----------|--------|------|
-| Lowest | npm packages | `node_modules/moflo-step-*` |
-| Medium | Built-in | Registered by `createRunner()` |
-| Highest | User directories | `workflows/steps/` or `.claude/workflows/steps/` |
-
-**Later sources override earlier ones by step type name.** A user step named `bash` replaces the built-in `bash` command.
-
-### JS/TS Step Files
-
-**Export a `StepCommand` object as the default export, or as `stepCommand` or `command` named export.**
-
-```javascript
-// workflows/steps/file-stats.js
-module.exports = {
-  type: 'file-stats',
-  description: 'Report file statistics',
-  configSchema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
-  capabilities: [{ type: 'fs:read' }],
-  validate(config) {
-    const errors = [];
-    if (!config.path) errors.push({ path: 'path', message: 'path is required' });
-    return { valid: errors.length === 0, errors };
-  },
-  async execute(config) {
-    const { readFileSync, statSync } = require('node:fs');
-    const content = readFileSync(config.path, 'utf-8');
-    return { success: true, data: { lines: content.split('\n').length, bytes: statSync(config.path).size } };
-  },
-  describeOutputs() { return [{ name: 'lines', type: 'number' }, { name: 'bytes', type: 'number' }]; },
-};
-```
-
-See `examples/spell-steps/file-stats.js` for a complete, well-commented example.
-
-### YAML Composite Steps
-
-**YAML files define reusable composite spell steps with declared inputs, tool dependencies, and sequential actions.**
-
-```yaml
-# workflows/steps/notify.yaml
-name: notify
-description: Log a formatted notification message
-inputs:
-  level:
-    type: string
-    required: false
-    default: "info"
-  message:
-    type: string
-    required: true
-actions:
-  - command: "echo [${inputs.level}] ${inputs.message}"
-```
-
-| YAML Field | Required | Description |
-|------------|----------|-------------|
-| `name` | Yes | Step type name (used as `type` in spell definitions) |
-| `description` | No | Human-readable description |
-| `tool` | No | Declares tool dependency (maps to `net` capability and prerequisites) |
-| `inputs` | No | Input schema with `type`, `required`, `default`, `description` per field |
-| `actions` | Yes | Sequential actions to execute; each has `tool`/`action`/`command` + `params` |
-
-**Use `${inputs.X}` in action params for input interpolation.** Required inputs are validated before execution.
-
-### npm Package Discovery
-
-**Install a package named `moflo-step-*` and its exported StepCommand is auto-discovered.**
-
-The loader reads `package.json` for a `moflo.stepCommand` field pointing to the entry file. Falls back to the package's `main` field if absent.
-
-```json
-{
-  "name": "moflo-step-slack-notify",
-  "main": "index.js",
-  "moflo": { "stepCommand": "lib/step.js" }
-}
-```
-
-### Configuring Step Discovery in createRunner
-
-**Pass `stepDirs` and `projectRoot` to `createRunner()` to enable pluggable step discovery.**
-
-```typescript
-import { createRunner } from 'moflo/dist/src/cli/spells/index.js';
-
-const runner = createRunner({
-  stepDirs: ['workflows/steps/', '.claude/workflows/steps/'],
-  projectRoot: process.cwd(),  // Enables npm moflo-step-* discovery
-});
-```
-
-### Invalid Files Are Warnings, Not Errors
+## Custom Step Commands
 
-**Files that don't export a valid StepCommand are skipped with a warning.** This prevents one bad file from breaking all step discovery. Invalid conditions: missing exports, wrong interface shape, syntax errors, malformed YAML.
+**To register custom step types, see `moflo-spell-custom-steps.md`.** That doc covers the three extension paths (JS/TS step files, YAML composite steps, `moflo-step-*` npm packages), priority ordering, and how to configure `createRunner()` for discovery.
 
 ---
 
@@ -505,6 +407,7 @@ Credential values listed in `RunnerOptions.credentialValues` are automatically r
 
 ## See Also
 
+- `.claude/guidance/shipped/moflo-spell-custom-steps.md` — Pluggable step commands: JS/TS, YAML, and `moflo-step-*` npm packages
 - `.claude/guidance/shipped/moflo-spell-connectors.md` — Connectors: resource adapters, registry, step-vs-connector decision
 - `.claude/guidance/shipped/moflo-spell-sandboxing.md` — Capability-based security for steps
 - `.claude/guidance/shipped/moflo-spell-engine-architecture.md` — Architecture decisions for Epic #100

package/.claude/guidance/shipped/moflo-subagents.md

@@ -138,3 +138,13 @@ npx flo memory store --namespace patterns --key "brief-descriptive-key" --value
 1. Report findings to coordinator
 2. Store learnings if you discovered something new
 3. Coordinator will mark your task as completed
+
+---
+
+## See Also
+
+- `.claude/guidance/shipped/moflo-task-icons.md` — Mandatory ICON + [Role] format for every `TaskCreate` and `Agent` description spawned by a coordinator
+- `.claude/guidance/shipped/moflo-claude-swarm-cohesion.md` — How task lists and swarm coordinators cooperate when subagents are spawned in batches
+- `.claude/guidance/shipped/moflo-memory-strategy.md` — The memory-search-first rule this protocol enforces, with namespace-selection guidance
+- `.claude/guidance/shipped/moflo-memorydb-maintenance.md` — How the memory namespaces are populated and refreshed; required reading when search returns no results
+- `.claude/guidance/shipped/moflo-core-guidance.md` — Full CLI/MCP reference including the spell gates that block subagent spawn before memory is searched

package/.claude/guidance/shipped/moflo-task-icons.md

@@ -61,3 +61,12 @@ The spinner is the primary visual feedback during agent execution. Without icons
 - What type of agent is working
 - Whether the right specialist was chosen
 - When agent types change during multi-step workflows
+
+---
+
+## See Also
+
+- `.claude/guidance/shipped/moflo-subagents.md` — Subagent protocol; `TaskCreate`/`Agent` icon rule is enforced as part of the spawning checklist
+- `.claude/guidance/shipped/moflo-claude-swarm-cohesion.md` — How task lists and swarms cooperate; icons distinguish swarm-spawned vs single-agent work
+- `.claude/guidance/shipped/moflo-user-facing-language.md` — Companion UX rule for any text shown to end users
+- `.claude/guidance/shipped/moflo-core-guidance.md` — Spell Gate that enforces icon format on `TaskCreate`

package/.claude/guidance/shipped/moflo-user-facing-language.md

@@ -32,3 +32,11 @@
 - Debug/trace logs gated behind verbose flags
 - Code comments and docstrings
 - Test descriptions
+
+---
+
+## See Also
+
+- `.claude/guidance/shipped/moflo-task-icons.md` — Companion UX rule: spinner text must use ICON + [Role] so non-technical users can identify the working agent
+- `.claude/guidance/shipped/moflo-spell-sandboxing.md` — Permission disclosure output where this language rule has the largest user-visible surface
+- `.claude/guidance/shipped/moflo-error-handling.md` — Sibling rule for what error messages must contain; this doc governs how those messages are phrased

package/.claude/guidance/shipped/moflo-yaml-reference.md

@@ -0,0 +1,191 @@
+# moflo.yaml + Runtime Environment Reference
+
+**Purpose:** Complete schema for `moflo.yaml`, runtime environment variable overrides, and `.mcp.json` setup. Reference this when configuring a moflo project, debugging "why is gate X not firing", or wiring moflo into a fresh repo.
+
+---
+
+## Project Configuration (moflo.yaml)
+
+Moflo reads `moflo.yaml` (or `moflo.config.json`) from the project root. All fields have sensible defaults — the file is optional. If it's missing on first run, `flo init` writes one with the defaults below.
+
+### Full Reference
+
+```yaml
+project:
+  name: "my-project"              # Project name (default: directory name)
+
+# Guidance/knowledge docs to index for semantic search
+guidance:
+  directories:                    # Directories to scan for .md files
+    - .claude/guidance            # Default
+    - docs/guides                 # Default
+  namespace: guidance             # Memory namespace for indexed docs
+
+# Source directories for code navigation map
+code_map:
+  directories:                    # Directories to scan for source files
+    - src                         # Default
+    - packages
+    - lib
+    - app
+  extensions: [".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".rs", ".java"]
+  exclude: [node_modules, dist, .next, coverage, build, __pycache__, target, .git]
+  namespace: code-map
+
+# Workflow gates (enforced via Claude Code hooks)
+# Memory-first is enforced at the scan/read layer (Glob, Grep, Read gates).
+# Agent spawning is never blocked — SubagentStart hook injects guidance directive.
+gates:
+  memory_first: true              # Block Glob/Grep/Read until memory is searched
+  task_create_first: true         # Advisory reminder before Agent tool (not blocking)
+  context_tracking: true          # Track context bracket (FRESH/MODERATE/DEPLETED/CRITICAL)
+
+# Auto-index on session start
+auto_index:
+  guidance: true                  # Run flo-index (guidance RAG indexer)
+  code_map: true                  # Run flo-codemap (structural code index)
+
+# Memory backend
+memory:
+  backend: sql.js                 # sql.js (WASM) | json
+  embedding_model: Xenova/all-MiniLM-L6-v2   # 384-dim neural embeddings
+  namespace: default              # Default namespace for memory operations
+
+# Hook toggles (all on by default — disable to slim down)
+hooks:
+  pre_edit: true                  # Track file edits for learning
+  post_edit: true                 # Record edit outcomes, train neural patterns
+  pre_task: true                  # Get agent routing before task spawn
+  post_task: true                 # Record task results for learning
+  gate: true                      # Workflow gate enforcement (memory-first at scan/read layer)
+  route: true                     # Intelligent task routing on each prompt
+  stop_hook: true                 # Session-end persistence and metric export
+  session_restore: true           # Restore session state on start
+  notification: true              # Hook into Claude Code notifications
+
+# Model preferences (haiku, sonnet, opus)
+models:
+  default: opus                   # General tasks
+  research: sonnet                # Research/exploration agents
+  review: opus                    # Code review agents
+  test: sonnet                    # Test-writing agents
+
+# Intelligent model routing (auto-selects haiku/sonnet/opus per task)
+model_routing:
+  enabled: false                  # Set true to enable dynamic routing
+  confidence_threshold: 0.85      # Min confidence before escalating
+  cost_optimization: true         # Prefer cheaper models when confident
+  circuit_breaker: true           # Penalize models that fail repeatedly
+  # agent_overrides:
+  #   security-architect: opus
+  #   researcher: sonnet
+
+# Status line display
+status_line:
+  enabled: true                   # Show status line at all
+  branding: "Moflo V4"            # Text in status bar
+  mode: single-line               # single-line (default) or dashboard (multi-line)
+  show_git: true                  # Git branch, changes, ahead/behind
+  show_model: true                # Current model name
+  show_session: true              # Session duration
+  show_intelligence: true         # Intelligence % indicator
+  show_swarm: true                # Active swarm agents count
+  show_hooks: true                # Enabled hooks count
+  show_mcp: true                  # MCP server count
+  show_security: true             # CVE/security status (dashboard only)
+  show_adrs: true                 # ADR compliance (dashboard only)
+  show_tests: true                # Test file count (dashboard only)
+
+# Spell step sandboxing (OS-level process isolation for bash steps)
+# Platform support: macOS (sandbox-exec), Linux/WSL (bwrap). Windows has no OS sandbox.
+sandbox:
+  enabled: false                  # Set to true to wrap bash steps in an OS sandbox
+  tier: auto                      # auto | denylist-only | full
+```
+
+If your `moflo.yaml` predates the `sandbox:` block, it is auto-appended on the next session start — you never need to re-run `moflo init` after a version bump.
+
+### Key Behaviors
+
+| Config | Effect |
+|--------|--------|
+| `auto_index.guidance: false` | Skip guidance indexing on session start |
+| `auto_index.code_map: false` | Skip code map generation on session start |
+| `gates.memory_first: true` | Block Glob/Grep/Read until memory is searched first |
+| `gates.task_create_first: true` | Advisory reminder before Agent tool (not blocking) |
+| `gates.context_tracking: true` | Show FRESH/MODERATE/DEPLETED/CRITICAL context bracket |
+| `hooks.pre_edit: false` | Disable file-edit tracking (skips pre-edit hook) |
+| `hooks.post_edit: false` | Disable edit outcome recording and neural training |
+| `hooks.pre_task: false` | Disable agent routing recommendations before spawn |
+| `hooks.post_task: false` | Disable task result recording for learning |
+| `hooks.gate: false` | Disable all workflow gates (memory-first, task-create-first) |
+| `hooks.route: false` | Disable intelligent task routing on each prompt |
+| `hooks.stop_hook: false` | Disable session-end persistence and metric export |
+| `hooks.notification: false` | Disable notification hook |
+| `model_routing.enabled: true` | Auto-select haiku/sonnet/opus based on task complexity |
+| `status_line.mode: dashboard` | Switch to multi-line status display |
+| `status_line.show_swarm: false` | Hide swarm agent count from status bar |
+| `sandbox.enabled: true` | Wrap bash steps in an OS sandbox (macOS/Linux/WSL) — absolute disable when `false`, regardless of tier |
+| `sandbox.tier: full` | Require OS sandbox; throw at runtime if the platform tool is unavailable |
+| `sandbox.tier: denylist-only` | Keep Layer 1 denylist only; skip OS isolation even when enabled |
+
+---
+
+## Environment Variables
+
+Config is loaded from `moflo.yaml` at the project root — there is no env var that points at a config file. The variables below override specific values at runtime:
+
+```bash
+# Logging
+CLAUDE_FLOW_LOG_LEVEL=info               # debug | info | warn | error
+
+# MCP Server (stdio transport — no port)
+CLAUDE_FLOW_MCP_TRANSPORT=stdio
+
+# Memory backend
+CLAUDE_FLOW_MEMORY_BACKEND=hybrid        # hybrid | sqlite | agentdb (legacy)
+CLAUDE_FLOW_MEMORY_TYPE=sqlite           # storage type override
+```
+
+Variable names retain the `CLAUDE_FLOW_` prefix for backward compatibility with consumers upgraded from claude-flow.
+
+---
+
+## .mcp.json — MCP Tool Wiring
+
+### Project-Level (Recommended)
+
+Configure `.mcp.json` in the project root:
+
+```json
+{
+  "mcpServers": {
+    "moflo": {
+      "command": "node",
+      "args": ["node_modules/moflo/bin/cli.js", "mcp", "start"]
+    }
+  }
+}
+```
+
+`flo init` writes this file automatically; only edit it if you need a non-default invocation (custom node binary, alternate `args`, etc.).
+
+### Alternative: Global MCP Registration
+
+```bash
+claude mcp add moflo -- npx moflo@alpha
+npx flo daemon start
+npx flo doctor --fix
+```
+
+Global registration is useful for ad-hoc projects where you don't want to commit `.mcp.json`. For long-lived projects, prefer the project-level form so the configuration is version-controlled with the code.
+
+---
+
+## See Also
+
+- `.claude/guidance/shipped/moflo-core-guidance.md` — Hub: getting started, anti-drift defaults, troubleshooting
+- `.claude/guidance/shipped/moflo-cli-reference.md` — Commands, agents, hooks, hive-mind, ruvector — the surfaces this config gates
+- `.claude/guidance/shipped/moflo-spell-sandboxing.md` — What `sandbox:` actually does at the bash-step boundary, with capability/permission interaction
+- `.claude/guidance/shipped/moflo-session-start.md` — Where these config fields are read and applied during session start
+- `.claude/guidance/shipped/moflo-settings-injection.md` — What moflo writes into `.claude/settings.json` (the hook wiring; complementary to `moflo.yaml` toggles)

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

@@ -32,7 +32,7 @@ Ask the user:
 
 **Important:** Simple service integrations (Slack webhook, S3 upload, Jira comment) should compose existing connectors (`http`, `github-cli`, `playwright`) in spell YAML — no dedicated connector needed. However, platforms requiring complex multi-step browser interaction (like Outlook.com web UI) DO warrant a dedicated connector. See `.claude/skills/spell-builder/architecture.md` for the decision tree.
 
-**Documentation requirement:** When creating any new step command or connector, you MUST also create a README.md following `.claude/guidance/internal/guidance-rules.md`. Use existing READMEs in `.claude/skills/spell-builder/steps/` or `connectors/` as templates. Apply automatically — the user should never need to ask.
+**Documentation requirement:** When creating any new step command or connector, you MUST also create a README.md following `.claude/guidance/shipped/moflo-guidance-rules.md`. Use existing READMEs in `.claude/skills/spell-builder/steps/` or `connectors/` as templates. Apply automatically — the user should never need to ask.
 
 Then follow the appropriate section below.
 

package/.claude/skills/guidance/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: guidance
+description: Add, edit, or audit guidance docs in this project's .claude/guidance/ directory following moflo's universal guidance rules. Default mode walks the user through one doc (creating or improving it); the -a flag audits every doc in the directory and offers per-file improvements.
+arguments: "[-a] [<topic-or-path>]"
+---
+
+# /guidance — Author and audit project guidance
+
+Help the user write, edit, or audit guidance files in their `.claude/guidance/` directory so Claude actually follows the rules they wrote. The skill applies the universal rules from `.claude/guidance/shipped/moflo-guidance-rules.md` — that doc is the single source of truth, do not paraphrase or duplicate it here.
+
+**Arguments:** $ARGUMENTS
+
+## Modes
+
+| Mode | Trigger | What it does |
+|------|---------|--------------|
+| Single-doc | no flag, optional `<topic-or-path>` arg | Walk the user through creating one new doc OR improving one existing doc |
+| Audit | `-a` flag | Scan every `.md` in `.claude/guidance/` (recursively), score each against the rules, present a triage report, then offer to fix per-file or in batch |
+
+## Step 0 — Memory First
+
+Before reading any files, run a memory search:
+
+```
+mcp__moflo__memory_search { query: "guidance rules writing project conventions", namespace: "guidance" }
+```
+
+This pulls the user's project-specific guidance conventions (if any) plus the moflo universal rules into context. The memory-first gate will block file reads otherwise.
+
+## Step 1 — Pick the Mode and Target
+
+Parse the argument:
+
+| Input | Mode | Target |
+|-------|------|--------|
+| empty | single-doc | Ask the user for a topic; default destination is `.claude/guidance/<kebab-topic>.md` |
+| `<topic>` (no slash) | single-doc | Use `.claude/guidance/<kebab-topic>.md`; if it exists, edit; else create |
+| `<path>` (has `.claude/guidance/`) | single-doc | Edit that exact file; if it doesn't exist, create at that path |
+| `-a` | audit | All `.md` files under `.claude/guidance/` recursively |
+| `-a <subdir>` | audit | All `.md` files under `.claude/guidance/<subdir>/` recursively |
+
+If single-doc and the file already exists, briefly summarize what it contains (one sentence) before walking the user through edits — confirm you have the right file.
+
+## Step 2 — Single-Doc Mode
+
+Apply the universal rules from `.claude/guidance/shipped/moflo-guidance-rules.md`. The rules cover (do not paraphrase — read the source):
+
+1. Lead with `**Purpose:**` line after the H1
+2. Be imperative, not descriptive
+3. Use tables for decision logic
+4. Code examples must be concrete
+5. Keep files under 500 lines
+6. Headings must be specific
+7. Avoid the listed anti-patterns
+8. Optimize for RAG chunking
+9. End with a `## See Also` section
+
+### Creating a new doc — scaffold this shape
+
+```markdown
+# <Specific Title — what this doc is and when to use>
+
+**Purpose:** <one sentence on what this doc covers and when to reference it>
+
+---
+
+## <Specific H2 — first actionable rule or topic>
+
+<Imperative rule, then rationale, then example.>
+
+---
+
+## <Specific H2 — second>
+
+<Same shape.>
+
+---
+
+## See Also
+
+- `.claude/guidance/<related-doc>.md` — One-line description of why related
+- `.claude/guidance/<another>.md` — One-line description
+```
+
+After scaffolding, ask the user 2–4 targeted questions to populate the body — never auto-write opinionated content into the user's project. Their guidance must reflect their conventions, not Claude's.
+
+### Editing an existing doc — checklist before proposing changes
+
+For the loaded file, evaluate against the universal rules and report findings as a short table BEFORE editing:
+
+| Check | Status |
+|-------|--------|
+| Has `**Purpose:**` line right after H1 | yes / no |
+| Has `## See Also` section at end | yes / no |
+| Under 500 lines | <count> lines |
+| H2 headings are specific (not "Overview", "Configuration", "Examples") | list any generic ones |
+| Uses imperative voice for rules ("must"/"always"/"never") not hedged ("should"/"might"/"consider") | list hedged phrases found |
+| Has prose preamble before first rule | yes / no |
+
+Then propose edits as concrete diffs — never rewrite the whole file unless the user asks.
+
+## Step 3 — Audit Mode (`-a`)
+
+When `-a` is passed, scan the guidance directory and produce a triage report. Walk the directory yourself with `Glob` and `Read`; do not delegate to a subagent for the audit itself unless the user has 30+ files.
+
+For each `.md` file:
+
+1. Count lines (`wc -l` via Bash, or read + split)
+2. Check for `**Purpose:**` line right after H1
+3. Check for `## See Also` (Title Case, capital A) at end
+4. Look for generic headings: `^## (Overview|Configuration|Examples|Rules|Notes|Details|Information)$`
+5. Look for hedged language: `\b(should|might|consider|may want to)\b` in rule contexts
+6. Detect prose preambles (>3 paragraphs between H1 and first H2 rule)
+
+Render the report as a sortable table with one row per file, columns: file, lines, has-purpose, has-see-also, generic-headings count, hedged count. Highlight the worst offenders first.
+
+After the table, list the **top 3–5 priority fixes** in plain English (not table format). For each, explain WHY (rule citation) and propose either a per-file fix or a batch fix.
+
+Ask the user which to apply, then walk through the chosen fixes one at a time. **Never apply audit fixes without explicit per-file confirmation** — guidance is high-leverage; silent edits are dangerous.
+
+## Step 4 — After Editing
+
+Once the user confirms the doc looks right:
+
+1. Save the file via `Write` (new) or `Edit` (existing).
+2. If you added a new doc, ask the user which existing doc should link to it via See Also (rule #9 needs bidirectional links to work).
+3. Suggest re-indexing if the user runs moflo: `node bin/index-guidance.mjs` (or just wait for next session-start auto-reindex).
+
+## Cheatsheet — Universal Rules Recap
+
+The full rules live in `.claude/guidance/shipped/moflo-guidance-rules.md`. Quick recap:
+
+| # | Rule | One-line |
+|---|------|----------|
+| 1 | Structure for scanability | Purpose line + specific H2s + rule-first ordering |
+| 2 | Imperative voice | "Must" / "always" / "never", not "should" / "might" |
+| 3 | Tables for decisions | Conditional logic in tables, not nested bullets |
+| 4 | Concrete examples | Realistic values, not `[placeholder]` |
+| 5 | <500 lines | Split by concern when over |
+| 6 | Specific headings | Not "Overview" / "Configuration" |
+| 7 | Anti-patterns | Single source of truth, no preambles, prose for rules (not code comments) |
+| 8 | RAG chunking | 5–30 lines per H2, self-contained openings, `---` between sections |
+| 9 | See Also | Title Case, end of every file, relative paths |
+
+## Important
+
+- **Memory-first is mandatory.** Always run `mcp__moflo__memory_search` in step 0 — the gate blocks reads otherwise.
+- **Never duplicate the rules in this skill.** Reference `.claude/guidance/shipped/moflo-guidance-rules.md` and ask the user to read it if they want depth.
+- **Never auto-write opinionated content.** Guidance is the user's project policy; ask before injecting your own opinions.
+- **Confirm per file in audit mode.** Bulk edits to the user's guidance directory are high-blast-radius — confirm each one.
+- **The `moflo-` filename prefix is moflo-only.** Consumer projects writing their own guidance do not need it; it exists to avoid collisions when moflo's shipped guidance syncs into a consumer's directory.
+
+## See Also
+
+- `.claude/guidance/shipped/moflo-guidance-rules.md` — Universal writing rules this skill enforces
+- `.claude/guidance/shipped/moflo-memory-strategy.md` — How well-written guidance feeds the RAG index
+- `.claude/guidance/shipped/moflo-task-icons.md` — UX rule the skill checks for any TaskCreate examples in the user's guidance
+- `.claude/guidance/shipped/moflo-user-facing-language.md` — Companion rule for any user-visible text the user's guidance discusses

package/.claude/skills/publish/SKILL.md

@@ -21,6 +21,14 @@ Automated release pipeline for moflo. Bumps version, commits, builds, tests, run
 /publish patch        # explicit patch bump
 ```
 
+## Pre-Publish Gate — REQUIRED
+
+**Before Step 1, walk the full pre-flight checklist in `.claude/guidance/internal/pre-publish-rules.md`.** That document is the authoritative ruleset for every publish — the seven layered gates (lint, build, tests, doctor, smoke, populated smoke, manifest sanity) plus the cross-platform and consumer-install posture checks. Do not paraphrase or shortcut the rules here; read them and confirm every item.
+
+If you cannot confirm all ten checklist items at the bottom of `pre-publish-rules.md`, STOP. Fix the failing gate first and only then resume from Step 1 below. Skipping the gate to "just get this small change out" is the antipattern that produced the historical incidents named in the rules doc.
+
+---
+
 ## Step-by-Step Procedure
 
 Follow docs/BUILD.md exactly. Every step must succeed before proceeding to the next.
@@ -162,3 +170,11 @@ Installed:  moflo@<new-version> (devDependency)
 - Never install moflo globally — it is always a local devDependency
 - If any step fails, stop and fix the issue before proceeding — do not skip steps
 - The `prepublishOnly` script in package.json runs `npm run build` automatically, so npm publish will fail-fast on any TypeScript or asset-bundling error
+- Pre-publish rules live in `.claude/guidance/internal/pre-publish-rules.md` — never duplicate or paraphrase them in this skill; reference and follow
+
+## See Also
+
+- `.claude/guidance/internal/pre-publish-rules.md` — Mandatory cross-platform + consumer-install gates that gate every publish
+- `docs/BUILD.md` — Step-by-step build/publish process this skill mirrors
+- `.claude/guidance/internal/dogfooding.md` — Why we catch consumer-facing regressions first as our own dependency
+- `harness/consumer-smoke/README.md` — Smoke harness profiles (clean + populated) that prove a consumer install works

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

@@ -356,7 +356,7 @@ Write the updated YAML back to the original file (or a new path if requested).
 
 **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/internal/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 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.
 
 ### Connectors
 
@@ -371,7 +371,7 @@ Write the updated YAML back to the original file (or a new path if requested).
 
 **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/internal/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.
+**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.
 

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/internal/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/shipped/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`