workflow-schema-composer

What this skill does

# Workflow Schema Composer

Generate complete, valid workflow definitions from skill recommendations.

## Purpose

Transform the output from skill-capability-matcher into a ready-to-use looplia workflow markdown file that follows the v0.6.2 schema.

## Process

### Step 1: Receive Inputs

From skill-capability-matcher output:
- Skill sequence with step IDs
- Mission descriptions for each step
- Data flow dependencies
- Original user requirements
- **Explicit name (if `--name` flag was provided)** - use this exact name for the workflow

### Step 1.5: Parse User Preferences from Enriched Prompt (v0.6.4)

**CRITICAL: User preferences from wizard answers MUST be incorporated into step missions.**

When the enriched prompt contains "User clarifications: Q: ... A: ..." sections, extract each preference:

**Example enriched prompt:**
```
/build search hackernews for AI news. User clarifications: Q: Which social media platforms? A: twitter, linkedin. Q: How many articles? A: top5. Q: Focus areas? A: llm, adoption. Q: Output format? A: posts
```

**Extract as structured preferences:**

| Question Pattern | Preference Key | Value | Inject Into |
|-----------------|----------------|-------|-------------|
| "platforms" / "social media" | PLATFORMS | twitter, linkedin | Output/social step mission |
| "how many" / "articles" / "count" | COUNT | 5 | Search/filter step mission |
| "focus" / "areas" / "topics" | FOCUS | llm, adoption | Search and analysis missions |
| "format" / "output" / "include" | FORMAT | posts | Final output step mission |

**Preference Injection Rules:**

1. **COUNT preferences** → Add to search/fetch step: "Find **top 5** articles..."
2. **FOCUS preferences** → Add to search and analysis: "...focusing on **LLM and adoption** trends"
3. **PLATFORM preferences** → Add to output step: "...optimized for **twitter and linkedin**"
4. **FORMAT preferences** → Add to output step: "Create **posts** (not reports)..."

### Step 2: Design Steps

For each recommended skill:

```yaml
- id: {suggestedStepId}
  skill: {skill-name}
  mission: |
    {mission description from matcher}
  needs: [{dependencies}]
  input: {input path(s)}
  output: {output path}
  model: {optional model override}
  validate:
    required_fields: [{fields}]
```

### Step 3: Resolve Dependencies

Use `dataFlow` from matcher:
- Steps with no dependencies: `needs:` is omitted
- Dependent steps: list all required step IDs in `needs:`
- Final step: add `final: true`

### Step 4: Design Input/Output Paths

Use variable substitution:
- `${{ sandbox }}/inputs/content.md` - Initial input (for workflows requiring input)
- `${{ sandbox }}/outputs/{step-id}.json` - Step outputs
- `${{ steps.{id}.output }}` - Reference previous step output

#### Input-Less Capable Skills (v0.6.3)

These skills can operate WITHOUT an input field - they fetch/generate data autonomously:

| Skill | Capability |
|-------|------------|
| `search` | Web search, API queries, autonomous data fetching |

**When a workflow's first step uses an input-less capable skill:**
1. **OMIT the `input:` field entirely** from that step
2. The mission description drives the skill's behavior
3. Subsequent steps reference the output: `${{ steps.{id}.output }}`

**Example input-less first step:**
```yaml
- id: fetch-data
  skill: browser-research
  mission: |
    Search the web for recent technology trends.
    Extract titles, URLs, and key details.
  output: ${{ sandbox }}/outputs/data.json
  # NO input field - browser-research operates autonomously
```

### Step 5: Suggest Validation

Based on skill output type:
- Analysis skills: `required_fields: [contentId, headline, keyThemes]`
- Idea skills: `required_fields: [contentId, hooks, angles]`
- Assembly skills: `required_fields: [contentId, suggestedOutline]`

### Step 6: Compose Frontmatter (v0.7.0)

**CRITICAL: If `--name` flag was provided, use that exact name. Do not derive or modify it.**

```yaml
---
name: {explicit-name OR derived-from-description}
version: 1.0.0
description: {user's original description, cleaned up}

# v0.7.0: Explicit skills declaration for selective plugin loading
skills:
  - {skill-name-1}
  - {skill-name-2}
  - ...

steps:
  - id: ...
---
```

**Skills Declaration (v0.7.0):**
Extract unique skill names from all step recommendations and list them in the `skills:` field.
This enables selective plugin loading at runtime - only required skills are loaded.

Naming rules:
1. If `--name article-summary` was provided → use `article-summary` exactly
2. If no `--name` → derive from description (e.g., "analyze videos" → "video-analyzer")
3. Always use kebab-case for names
4. Always include `skills:` field with all unique skills from steps

### Step 7: Generate Markdown Body

Add usage documentation:

**For workflows requiring input:**
```markdown
# {Workflow Name}

{Brief description}

## Usage

```bash
looplia run {workflow-name} --file <content.md>
```
```

**For input-less workflows (v0.6.3):**
```markdown
# {Workflow Name}

{Brief description}

## Usage

```bash
looplia run {workflow-name}
```

No input required - this workflow uses autonomous skills to fetch data.
```

**Steps section:**
```markdown
## Steps

1. **{step-id}**: {brief description}
2. ...
```

## Output Format

Return a JSON object (v0.7.3: used by CLI for artifact persistence):

```json
{
  "filename": "video-to-blog.md",
  "content": "---\nname: video-to-blog\nversion: 1.0.0\n...\n---\n\n# Video to Blog Workflow\n..."
}
```

**Important**: `content` MUST be the complete, ready-to-write markdown file including:
- Full YAML frontmatter (between `---` delimiters)
- Markdown body (usage docs, steps section)

The CLI writes this content directly to `{workspace}/workflows/{filename}`.

## Schema Reference

See SCHEMA.md in this skill directory for the complete v0.6.2 workflow schema.

## Validation Rules (v0.6.3)

1. **`skill:` is REQUIRED** - Every step must have a skill
2. **`mission:` is REQUIRED** - Every step must have a mission
3. **`run:` is FORBIDDEN** - Never use the old agent syntax
4. **Step IDs must be unique** - No duplicates
5. **Dependencies must exist** - All `needs:` references must be valid
6. **No circular dependencies** - Validate topological ordering
7. **Respect explicit `--name`** - If provided, use that exact name for filename and `name:` field
8. **Input-less steps (v0.6.3)** - Steps using `search` skill may OMIT `input:` field entirely

## Example Output

```yaml
---
name: video-to-blog
version: 1.0.0
description: Analyze YouTube videos and create blog outlines

# v0.7.0: Explicit skills declaration for selective plugin loading
skills:
  - media-reviewer
  - idea-synthesis
  - writing-kit-assembler

steps:
  - id: analyze-content
    skill: media-reviewer
    mission: |
      Deep analysis of video transcript. Extract key themes,
      important quotes with timestamps, and narrative structure.
    input: ${{ sandbox }}/inputs/content.md
    output: ${{ sandbox }}/outputs/analysis.json
    model: haiku
    validate:
      required_fields: [contentId, headline, keyThemes, importantQuotes]

  - id: generate-ideas
    skill: idea-synthesis
    mission: |
      Generate hooks, angles, and questions from the analysis.
      Read user profile for personalization context.
    needs: [analyze-content]
    input: ${{ steps.analyze-content.output }}
    output: ${{ sandbox }}/outputs/ideas.json
    validate:
      required_fields: [contentId, hooks, angles, questions]

  - id: build-outline
    skill: writing-kit-assembler
    mission: |
      Create structured blog outline with sections, key points,
      and supporting quotes from analysis and ideas.
    needs: [analyze-content, generate-ideas]
    input:
      - ${{ steps.analyze-content.output }}
      - ${{ steps.generate-ideas.output }}
    output: ${{ sandbox }}/outputs/outline.json
    final: true
    validate:
      required_fields: [contentId, suggestedOutline]
---

# Video to Blog Workflow

Transform video content into stru