@looplia/looplia-cli 0.6.6

package/plugins/looplia-core/skills/workflow-validator/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: workflow-validator
+description: |
+  This skill should be used when the user wants to validate a looplia workflow output,
+  check if an artifact meets validation criteria, or debug validation failures. Use when
+  someone says "validate this looplia output", "check if the workflow output is valid",
+  "verify the artifact JSON", or "debug why validation failed".
+
+  Runs deterministic validation scripts against JSON artifacts. Primarily used for manual
+  retry/debugging since automatic validation is handled by PostToolUse hooks. Part of
+  looplia's one step → one skill-executor → multiple skills architecture.
+---
+
+# Workflow Validator Skill
+
+Validates JSON artifacts against validation criteria using deterministic script execution.
+
+## Automatic Validation via Hook (v0.6.0)
+
+As of v0.6.0, the `PostToolUse:Write` hook **automatically** calls this validation script whenever an artifact is written to `sandbox/*/outputs/*.json`.
+
+**You typically don't need to manually invoke this skill** - the hook handles it.
+
+### When to Manually Use This Skill
+
+Use this skill only in these scenarios:
+- **Retrying after validation failure** - when the hook blocked a write and you need to debug
+- **Debugging validation issues** - to see detailed check results
+- **Checking artifacts outside the normal workflow** - for ad-hoc validation
+- **Pre-checking before write** - to validate data before writing to sandbox
+
+## What This Skill Does
+
+- Reads validation criteria from `sandbox/{id}/validation.json`
+- Runs deterministic validation script (no LLM tokens consumed)
+- Returns pass/fail status with detailed check results
+- Enables workflow completion verification
+
+## Validation Process
+
+### Step 1: Read Validation Criteria
+
+Read the validation manifest at `sandbox/{id}/validation.json`:
+
+```json
+{
+  "workflow": "writing-kit",
+  "version": "1.0.0",
+  "sandboxId": "article-2025-12-18-xk7m",
+  "steps": {
+    "summary": {
+      "output": "outputs/summary.json",
+      "validate": {
+        "required_fields": ["contentId", "headline", "tldr", "keyThemes"],
+        "min_quotes": 3,
+        "min_key_points": 5
+      },
+      "validated": false
+    }
+  }
+}
+```
+
+### Step 2: Run Validation Script
+
+Execute the validation script with artifact path and criteria:
+
+```bash
+bun scripts/validate.ts <artifact-path> '<criteria-json>'
+```
+
+Example:
+```bash
+bun scripts/validate.ts sandbox/podcast-2024-12-08-ai/outputs/summary.json '{"required_fields":["contentId","headline"],"min_quotes":3}'
+```
+
+### Step 3: Parse Results
+
+The script returns JSON with pass/fail and individual checks:
+
+```json
+{
+  "passed": true,
+  "checks": [
+    { "name": "has_contentId", "passed": true, "message": "OK" },
+    { "name": "has_headline", "passed": true, "message": "OK" },
+    { "name": "min_quotes", "passed": true, "message": "Found 5 quotes (min: 3)" }
+  ]
+}
+```
+
+### Step 4: Handle Results
+
+**If validation passes:**
+- Update `validation.json` to set `validated: true` for this output
+- Continue to next workflow step
+
+**If validation fails:**
+- Review failed checks
+- Either retry the subagent with feedback
+- Or report the issue to the user
+
+## Validation Criteria Reference
+
+### required_fields
+Array of field names that must exist in the artifact:
+```json
+"required_fields": ["contentId", "headline", "tldr"]
+```
+
+### min_quotes
+Minimum number of items in `importantQuotes` array:
+```json
+"min_quotes": 3
+```
+
+### min_key_points
+Minimum number of items in `bullets` or key points array:
+```json
+"min_key_points": 5
+```
+
+### min_outline_sections
+Minimum number of outline sections:
+```json
+"min_outline_sections": 4
+```
+
+### has_hooks
+Requires `hooks` array with at least one item:
+```json
+"has_hooks": true
+```
+
+## Output Format
+
+The validation script returns:
+
+```json
+{
+  "passed": boolean,
+  "checks": [
+    {
+      "name": "check_name",
+      "passed": boolean,
+      "message": "Human-readable result"
+    }
+  ]
+}
+```
+
+## Important Rules
+
+- **Automatic validation via hook** - Hook handles validation on write; manual use only for retry/debugging
+- **Script is deterministic** - No LLM context consumed
+- **Update validation.json** - Mark steps validated when passed (v0.6.0 uses `.steps` not `.outputs`)
+- **Retry on failure** - Give subagent feedback on what failed
+- **Check dependencies** - Ensure required steps are validated before dependent steps
+- **Use exact paths** - Artifact paths are relative to workspace root
+
+## Script Location
+
+The validation script is at:
+```
+.claude/skills/workflow-validator/scripts/validate.ts
+```
+
+Run with Bun for TypeScript execution:
+```bash
+bun .claude/skills/workflow-validator/scripts/validate.ts <artifact> '<criteria>'
+```

package/plugins/looplia-core/skills/workflow-validator/scripts/validate.ts

@@ -0,0 +1,244 @@
+#!/usr/bin/env bun
+/**
+ * Workflow Validator Script (v0.6.0)
+ *
+ * Deterministic validation of workflow artifacts against criteria.
+ * Runs outside LLM context - no tokens consumed.
+ *
+ * Usage:
+ *   bun validate.ts <artifact-path> '<criteria-json>'
+ *
+ * Example:
+ *   bun validate.ts contentItem/session-123/summary.json '{"required_fields":["contentId"],"min_quotes":3}'
+ *
+ * @see docs/DESIGN-0.6.0.md
+ */
+
+import { readFile } from "node:fs/promises";
+
+type ValidationCheck = {
+  name: string;
+  passed: boolean;
+  message: string;
+};
+
+type ValidationResult = {
+  passed: boolean;
+  checks: ValidationCheck[];
+};
+
+type ValidationCriteria = {
+  required_fields?: string[];
+  min_quotes?: number;
+  min_key_points?: number;
+  min_outline_sections?: number;
+  has_hooks?: boolean;
+  [key: string]: unknown;
+};
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+
+  if (args.length < 2) {
+    console.error("Usage: bun validate.ts <artifact-path> '<criteria-json>'");
+    process.exit(1);
+  }
+
+  const artifactPath = args[0];
+  const criteriaJson = args[1];
+
+  if (!(artifactPath && criteriaJson)) {
+    console.error("Error: Both artifact path and criteria JSON are required");
+    process.exit(1);
+  }
+
+  let data: Record<string, unknown>;
+  let criteria: ValidationCriteria;
+
+  // Read artifact file
+  try {
+    const content = await readFile(artifactPath, "utf-8");
+    data = JSON.parse(content) as Record<string, unknown>;
+  } catch (error) {
+    const result: ValidationResult = {
+      passed: false,
+      checks: [
+        {
+          name: "file_readable",
+          passed: false,
+          message: `Failed to read artifact: ${error instanceof Error ? error.message : "Unknown error"}`,
+        },
+      ],
+    };
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(0);
+  }
+
+  // Parse criteria JSON
+  try {
+    criteria = JSON.parse(criteriaJson) as ValidationCriteria;
+  } catch (error) {
+    const result: ValidationResult = {
+      passed: false,
+      checks: [
+        {
+          name: "criteria_valid",
+          passed: false,
+          message: `Invalid criteria JSON: ${error instanceof Error ? error.message : "Unknown error"}`,
+        },
+      ],
+    };
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(0);
+  }
+
+  // Run validation
+  const result = validate(data, criteria);
+  console.log(JSON.stringify(result, null, 2));
+}
+
+function validate(
+  data: Record<string, unknown>,
+  criteria: ValidationCriteria
+): ValidationResult {
+  const checks: ValidationCheck[] = [];
+
+  // Check required_fields
+  if (criteria.required_fields) {
+    checks.push(...checkRequiredFields(data, criteria.required_fields));
+  }
+
+  // Check min_quotes
+  if (criteria.min_quotes !== undefined) {
+    checks.push(checkMinQuotes(data, criteria.min_quotes));
+  }
+
+  // Check min_key_points
+  if (criteria.min_key_points !== undefined) {
+    checks.push(checkMinKeyPoints(data, criteria.min_key_points));
+  }
+
+  // Check min_outline_sections
+  if (criteria.min_outline_sections !== undefined) {
+    checks.push(checkMinOutlineSections(data, criteria.min_outline_sections));
+  }
+
+  // Check has_hooks
+  if (criteria.has_hooks === true) {
+    checks.push(checkHasHooks(data));
+  }
+
+  // Calculate overall pass/fail
+  const passed = checks.every((check) => check.passed);
+
+  return { passed, checks };
+}
+
+function checkRequiredFields(
+  data: Record<string, unknown>,
+  fields: string[]
+): ValidationCheck[] {
+  return fields.map((field) => {
+    const exists = hasField(data, field);
+    return {
+      name: `has_${field}`,
+      passed: exists,
+      message: exists ? "OK" : `Missing required field: ${field}`,
+    };
+  });
+}
+
+function checkMinQuotes(
+  data: Record<string, unknown>,
+  minQuotes: number
+): ValidationCheck {
+  const quotes = getArrayLength(data, "importantQuotes");
+  const passed = quotes >= minQuotes;
+  return {
+    name: "min_quotes",
+    passed,
+    message: passed
+      ? `Found ${quotes} quotes (min: ${minQuotes})`
+      : `Found ${quotes} quotes, need at least ${minQuotes}`,
+  };
+}
+
+function checkMinKeyPoints(
+  data: Record<string, unknown>,
+  minPoints: number
+): ValidationCheck {
+  const bullets = getArrayLength(data, "bullets");
+  const keyPoints = getArrayLength(data, "keyPoints");
+  const count = Math.max(bullets, keyPoints);
+  const passed = count >= minPoints;
+  return {
+    name: "min_key_points",
+    passed,
+    message: passed
+      ? `Found ${count} key points (min: ${minPoints})`
+      : `Found ${count} key points, need at least ${minPoints}`,
+  };
+}
+
+function checkMinOutlineSections(
+  data: Record<string, unknown>,
+  minSections: number
+): ValidationCheck {
+  const sections = getArrayLength(data, "suggestedOutline");
+  const passed = sections >= minSections;
+  return {
+    name: "min_outline_sections",
+    passed,
+    message: passed
+      ? `Found ${sections} outline sections (min: ${minSections})`
+      : `Found ${sections} sections, need at least ${minSections}`,
+  };
+}
+
+function checkHasHooks(data: Record<string, unknown>): ValidationCheck {
+  const hooksCount = getHooksCount(data);
+  const passed = hooksCount > 0;
+  return {
+    name: "has_hooks",
+    passed,
+    message: passed
+      ? `Found ${hooksCount} hooks`
+      : "No hooks found in artifact",
+  };
+}
+
+function getHooksCount(data: Record<string, unknown>): number {
+  const ideas = data.ideas as Record<string, unknown> | undefined;
+  if (ideas && Array.isArray(ideas.hooks)) {
+    return ideas.hooks.length;
+  }
+  if (Array.isArray(data.hooks)) {
+    return data.hooks.length;
+  }
+  return 0;
+}
+
+function hasField(data: Record<string, unknown>, field: string): boolean {
+  // Support nested fields with dot notation (e.g., "summary.headline")
+  const parts = field.split(".");
+  let current: unknown = data;
+
+  for (const part of parts) {
+    if (current === null || typeof current !== "object") {
+      return false;
+    }
+    current = (current as Record<string, unknown>)[part];
+  }
+
+  return current !== undefined && current !== null;
+}
+
+function getArrayLength(data: Record<string, unknown>, field: string): number {
+  const value = data[field];
+  if (Array.isArray(value)) {
+    return value.length;
+  }
+  return 0;
+}
+
+main();

package/plugins/looplia-writer/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "looplia-writer",
+  "description": "Writing domain plugin - Content analysis, idea generation, and writing-kit workflow",
+  "version": "0.6.5",
+  "author": {
+    "name": "Looplia"
+  },
+  "keywords": ["writing", "content", "analysis", "ideas"],
+  "homepage": "https://github.com/memorysaver/looplia-core"
+}

package/plugins/looplia-writer/README.md

@@ -0,0 +1,107 @@
+# Looplia Writer Plugin
+
+Writing domain plugin providing content analysis, idea generation, and writing-kit workflow.
+
+## Overview
+
+This plugin is a **domain plugin** that depends on `looplia-core` for workflow execution. It provides:
+
+- **Writing-kit workflow** for transforming content into actionable writing materials
+- **Specialized agents** for content analysis and idea generation
+- **Domain skills** for media review, content documentation, and writing enhancement
+
+## Workflow
+
+### writing-kit
+
+Transforms source content into a comprehensive writing kit:
+
+```
+/run writing-kit --file article.md
+```
+
+**Stages:**
+1. **content-analyzer** → `summary.json` - Deep content analysis
+2. **idea-generator** → `ideas.json` - Writing ideas and hooks
+3. **writing-kit-builder** → `writing-kit.json` - Final assembled kit
+
+## Agents
+
+### content-analyzer
+
+Deep content analysis using media-reviewer skill.
+
+**Skills:** media-reviewer, content-documenter
+
+**Output:** `summary.json` with:
+- Content ID, headline, TLDR
+- Key themes and talking points
+- Important quotes (verbatim)
+- Source metadata
+
+### idea-generator
+
+Generate writing ideas based on content analysis.
+
+**Skills:** user-profile-reader
+
+**Output:** `ideas.json` with:
+- Content ideas with hooks and angles
+- Format recommendations
+- Target audience alignment
+
+### writing-kit-builder
+
+Assemble final writing kit from all artifacts.
+
+**Skills:** user-profile-reader
+
+**Output:** `writing-kit.json` with:
+- Complete writing kit structure
+- All previous artifacts integrated
+- Ready-to-use writing materials
+
+## Skills
+
+| Skill | Purpose |
+|-------|---------|
+| media-reviewer | Analyze media content (transcripts, articles) |
+| content-documenter | Generate structured documentation |
+| id-generator | Create meaningful session IDs |
+| user-profile-reader | Load user preferences and style |
+| writing-enhancer | Enhance content quality |
+
+## Dependencies
+
+This plugin requires `looplia-core` which provides:
+- `/run` command for workflow execution
+- `workflow-executor` skill for orchestration
+- `workflow-validator` skill for output validation
+
+## Installation
+
+```bash
+looplia init
+```
+
+Both `looplia-core` and `looplia-writer` are installed together.
+
+## File Structure
+
+```
+plugins/looplia-writer/
+├── .claude-plugin/plugin.json    # Plugin manifest
+├── agents/
+│   ├── content-analyzer.md       # Stage 1 agent
+│   ├── idea-generator.md         # Stage 2 agent
+│   └── writing-kit-builder.md    # Stage 3 agent
+├── skills/
+│   ├── media-reviewer/SKILL.md
+│   ├── content-documenter/SKILL.md
+│   ├── id-generator/SKILL.md
+│   ├── user-profile-reader/SKILL.md
+│   └── writing-enhancer/SKILL.md
+├── workflows/
+│   └── writing-kit.md            # Workflow definition
+└── README.md                     # This file
+```