@looplia/looplia-cli 0.6.6

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@looplia/looplia-cli",
+  "version": "0.6.6",
+  "description": "Looplia CLI - AI-powered workflow automation tool",
+  "type": "module",
+  "license": "Elastic-2.0",
+  "author": "Looplia",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/memorysaver/looplia-core"
+  },
+  "homepage": "https://github.com/memorysaver/looplia-core",
+  "bugs": {
+    "url": "https://github.com/memorysaver/looplia-core/issues"
+  },
+  "keywords": [
+    "cli",
+    "ai",
+    "workflow",
+    "automation",
+    "looplia"
+  ],
+  "bin": {
+    "looplia": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "plugins"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "start": "node dist/index.js",
+    "test": "bun run build && bun test",
+    "test:watch": "bun test --watch",
+    "test:unit": "bun test commands/",
+    "test:e2e": "bun run build && bun test e2e/",
+    "check-types": "tsc --noEmit",
+    "copy-plugins": "rm -rf plugins && cp -r ../../plugins ./plugins",
+    "prepublishOnly": "bun run copy-plugins && bun run build"
+  },
+  "dependencies": {
+    "ink": "^6.5.1",
+    "react": "^19.2.1"
+  },
+  "devDependencies": {
+    "@looplia-core/config": "workspace:*",
+    "@looplia-core/core": "workspace:*",
+    "@looplia-core/provider": "workspace:*",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.2.7",
+    "tsup": "^8.5.1",
+    "typescript": "^5.0.0"
+  }
+}

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

@@ -0,0 +1,10 @@
+{
+  "name": "looplia",
+  "description": "Core workflow engine - Execute workflow-as-markdown definitions with validation-driven completion",
+  "version": "0.6.5",
+  "author": {
+    "name": "Looplia"
+  },
+  "keywords": ["workflow", "agentic", "automation", "validation"],
+  "homepage": "https://github.com/memorysaver/looplia-core"
+}

package/plugins/looplia-core/commands/build-workflow.md

@@ -0,0 +1,92 @@
+---
+description: Scaffold a new workflow definition
+---
+
+# Build Workflow
+
+Create a new workflow-as-markdown file with the proper structure.
+
+## Usage
+
+```
+/build-workflow <name>
+```
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `name` | Name for the new workflow (e.g., "research-kit") |
+
+## Example
+
+```
+/build-workflow research-kit
+```
+
+## Execution
+
+1. **Validate name**
+   - Check name is valid (lowercase, hyphens allowed)
+   - Check `workflows/{name}.md` doesn't already exist
+
+2. **Gather requirements**
+   - Ask user about workflow purpose
+   - Ask about expected outputs
+   - Ask about required agents
+
+3. **Generate workflow file**
+   - Create `workflows/{name}.md`
+   - Include YAML frontmatter with:
+     - name, description
+     - outputs with artifacts, agents, dependencies
+     - validation criteria placeholders
+   - Include markdown body with instructions
+
+4. **Generate agent stubs** (optional)
+   - Create `.claude/agents/{agent-name}.md` for each agent
+   - Include skills frontmatter
+   - Include task instructions
+
+## Template Structure
+
+```yaml
+---
+name: {name}
+description: {user-provided description}
+
+outputs:
+  first-step:
+    artifact: step1.json
+    agent: step1-agent
+    validate:
+      required_fields: [field1]
+
+  final-step:
+    artifact: final.json
+    agent: final-agent
+    requires: [first-step]
+    final: true
+    validate:
+      required_fields: [result]
+---
+
+# {Name} Workflow
+
+{Custom instructions for this workflow}
+
+## Context
+
+{What this workflow is for}
+
+## Expected Outputs
+
+{Description of each output}
+```
+
+## Output
+
+Report success with:
+- Path to created workflow file
+- Paths to any created agent files
+- Suggested next steps (customize, test with `/run`)

package/plugins/looplia-core/commands/build.md

@@ -0,0 +1,71 @@
+---
+description: Build a looplia workflow from natural language. Create looplia pipeline, generate workflow automation.
+---
+
+# Build Looplia Workflow
+
+Create a looplia workflow definition from natural language using the skills-first architecture.
+
+## Usage
+
+```
+/build [--name <name>] [description]
+```
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `description` | (Optional) Natural language description of what the workflow should do |
+| `--name <name>` | (Optional) Explicit workflow filename. If provided, use this exact name |
+
+## Execution
+
+**Use three skills in sequence:**
+
+1. `Skill("plugin-registry-scanner")` → Discover available skills from plugins
+2. `Skill("skill-capability-matcher")` → Match requirements to skills
+3. `Skill("workflow-schema-composer")` → Generate workflow file
+
+Each skill's SKILL.md contains implementation details. See `plugins/looplia-core/skills/` for full documentation.
+
+### Workflow
+
+1. Gather requirements (if no description provided, ask user)
+2. Call `Skill("plugin-registry-scanner")`
+3. Call `Skill("skill-capability-matcher")` with registry + requirements
+4. Call `Skill("workflow-schema-composer")` with matched skills + `--name` flag if provided
+5. Save generated workflow to `~/.looplia/workflows/{name}.md`
+6. Report success with run command example
+
+## Examples
+
+### Interactive Mode
+
+```
+User: /build
+Claude: What should this workflow do?
+User: Analyze YouTube videos and create blog outlines
+Claude: Created: ~/.looplia/workflows/video-to-blog.md (3 steps)
+        Run with: looplia run video-to-blog --file <transcript.md>
+```
+
+### Direct Mode
+
+```
+/build analyze videos and create blog outlines with key quotes
+```
+
+### With Explicit Name
+
+```
+/build --name article-summary summarize articles and extract key points
+```
+
+## Error Handling
+
+| Scenario | Response |
+|----------|----------|
+| No plugins installed | Error: "No skills found. Install looplia-writer plugin." |
+| No matching skills | Warning: Show capability gaps, offer partial workflow |
+| Invalid workflow generated | Retry generation with schema reminder |

package/plugins/looplia-core/commands/list-workflows.md

@@ -0,0 +1,55 @@
+---
+description: List available Looplia workflows
+---
+
+# List Workflows
+
+Show all available workflows in the `workflows/` directory.
+
+## Usage
+
+```
+/list-workflows
+```
+
+## Execution
+
+1. **Scan workflows directory**
+   - Read all `*.md` files in `workflows/`
+   - Parse YAML frontmatter from each
+
+2. **Extract metadata**
+   - name
+   - description
+   - outputs (list of step names)
+   - final output name
+
+3. **Display results**
+   - Table format with workflow info
+   - Show example usage
+
+## Example Output
+
+```
+Available Workflows
+===================
+
+| Workflow     | Description                  | Steps                          |
+|--------------|------------------------------|--------------------------------|
+| writing-kit  | Generate content writing kit | summary → ideas → writing-kit  |
+
+Usage:
+  /run writing-kit --file <path>
+```
+
+## No Workflows Found
+
+If no workflows exist:
+1. Report that no workflows are available
+2. Suggest using `/build-workflow` to create one
+3. Provide example: `/build-workflow my-workflow`
+
+## Related Commands
+
+- `/run <workflow-id> --file <path>` - Execute a workflow
+- `/build-workflow <name>` - Create a new workflow

package/plugins/looplia-core/commands/run.md

@@ -0,0 +1,50 @@
+---
+description: Execute a looplia workflow on content. Run looplia pipeline, start workflow automation.
+---
+
+# Execute Looplia Workflow
+
+Run a looplia workflow from `workflows/` on provided content.
+
+## Usage
+
+```
+/run <workflow-id> --file <path>
+/run <workflow-id> --sandbox-id <id>
+```
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `workflow-id` | Name of workflow (e.g., "writing-kit") |
+| `--file <path>` | Path to content file (creates new sandbox) |
+| `--sandbox-id <id>` | Resume existing sandbox |
+
+## Examples
+
+```
+/run writing-kit --file ~/articles/draft.md
+/run writing-kit --sandbox-id draft-2025-12-18-abc123
+```
+
+## Execution
+
+**Use the `Skill("workflow-executor")` to handle all execution.**
+
+The workflow-executor skill:
+1. Parses workflow YAML from `workflows/{workflow-id}.md`
+2. Creates/resumes sandbox
+3. Executes each step via `Task(skill-executor)`
+4. Manages validation state
+5. Returns final artifact
+
+See `plugins/looplia-core/skills/workflow-executor/SKILL.md` for implementation details.
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Workflow not found | Report available workflows via `/list-workflows` |
+| File not found | Report specific error with path |
+| Sandbox not found | Report available sandboxes |

package/plugins/looplia-core/hooks/hooks.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://code.claude.com/schemas/hooks.json",
+  "hooks": [
+    {
+      "event": "SessionStart",
+      "command": "echo '🚀 Looplia session started'",
+      "description": "Log session start"
+    },
+    {
+      "event": "PostToolUse",
+      "matcher": "Write",
+      "command": "./scripts/hooks/post-write-validate.sh",
+      "description": "Auto-validate artifacts written to sandbox outputs"
+    },
+    {
+      "event": "Stop",
+      "command": "./scripts/hooks/stop-guard.sh",
+      "description": "Guard workflow completion - block until all validated"
+    },
+    {
+      "event": "SessionStart",
+      "matcher": "compact",
+      "command": "./scripts/hooks/compact-inject-state.sh",
+      "description": "Re-inject sandbox state after context compact"
+    }
+  ]
+}

package/plugins/looplia-core/scripts/hooks/compact-inject-state.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+# Context Compact State Injection Hook (v0.6.0)
+# Triggered: When context is compacted (SessionStart:compact)
+# Action: Re-inject current sandbox progress into new context
+
+set -euo pipefail
+
+# Find active sandbox
+SANDBOX_BASE="${HOME}/.looplia/sandbox"
+if [[ ! -d "$SANDBOX_BASE" ]]; then
+  exit 0
+fi
+
+# Sort by modification time (newest first) to get most recent sandbox
+SANDBOX_DIR=$(ls -td "$SANDBOX_BASE"/*/ 2>/dev/null | head -1 | sed 's:/$::')
+if [[ -z "$SANDBOX_DIR" ]]; then
+  exit 0
+fi
+
+VALIDATION_JSON="$SANDBOX_DIR/validation.json"
+SANDBOX_ID=$(basename "$SANDBOX_DIR")
+
+if [[ ! -f "$VALIDATION_JSON" ]]; then
+  exit 0
+fi
+
+WORKFLOW=$(jq -r '.workflow // "unknown"' "$VALIDATION_JSON")
+
+# Build progress summary (v0.6.0 uses "steps" not "outputs")
+echo "=== Active Sandbox: $SANDBOX_ID ==="
+echo "Workflow: $WORKFLOW"
+echo ""
+echo "Progress:"
+jq -r '.steps | to_entries[] | "  - \(.key): \(if .value.validated then "✓ validated" else "⏳ pending" end)"' "$VALIDATION_JSON"
+echo ""
+echo "Next: Complete pending steps in dependency order."

package/plugins/looplia-core/scripts/hooks/post-write-validate.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+# Post-Write Artifact Validator Hook (v0.6.0)
+# Triggered: When Write tool completes
+# Action: Run semantic validation via validate.ts for sandbox outputs
+
+set -euo pipefail
+
+# Read JSON input from stdin
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+# Only process sandbox/ files (matches sandbox/{id}/outputs/*.json pattern)
+if [[ "$FILE_PATH" != *"/sandbox/"* ]]; then
+  exit 0
+fi
+
+# Check if it's in outputs/ directory
+if [[ "$FILE_PATH" != *"/outputs/"* ]]; then
+  exit 0
+fi
+
+# Extract sandbox directory and artifact name
+SANDBOX_DIR=$(dirname "$(dirname "$FILE_PATH")")
+ARTIFACT=$(basename "$FILE_PATH" .json)
+VALIDATION_JSON="$SANDBOX_DIR/validation.json"
+
+# Check for validation.json
+if [[ ! -f "$VALIDATION_JSON" ]]; then
+  exit 0
+fi
+
+# Use file locking to prevent race conditions when multiple writes happen concurrently
+# flock ensures exclusive access to validation.json during read-modify-write cycle
+LOCK_FILE="${VALIDATION_JSON}.lock"
+
+(
+  # Acquire exclusive lock (wait up to 30 seconds)
+  if ! flock -x -w 30 200; then
+    echo "Failed to acquire lock on validation.json" >&2
+    exit 1
+  fi
+
+  # Get validation criteria from validation.json (v0.6.0 uses "steps" not "outputs")
+  CRITERIA=$(jq -r --arg art "$ARTIFACT" '.steps[$art].validate // empty' "$VALIDATION_JSON" 2>/dev/null)
+
+  if [[ -z "$CRITERIA" || "$CRITERIA" == "null" ]]; then
+    # No criteria defined - just check JSON validity
+    if ! jq empty "$FILE_PATH" 2>/dev/null; then
+      echo "Validation failed for $ARTIFACT: Invalid JSON" >&2
+      exit 2
+    fi
+  else
+    # Run full semantic validation via validate.ts
+    SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+    VALIDATOR_SCRIPT="$SCRIPT_DIR/../../skills/workflow-validator/scripts/validate.ts"
+
+    if [[ -f "$VALIDATOR_SCRIPT" ]]; then
+      # Run the validation script
+      RESULT=$(bun "$VALIDATOR_SCRIPT" "$FILE_PATH" "$CRITERIA" 2>&1) || true
+      PASSED=$(echo "$RESULT" | jq -r '.passed // false' 2>/dev/null) || PASSED="false"
+
+      if [[ "$PASSED" != "true" ]]; then
+        echo "Semantic validation failed for $ARTIFACT:" >&2
+        echo "$RESULT" >&2
+        exit 2
+      fi
+    else
+      # Fallback to basic JSON check if validator script not found
+      if ! jq empty "$FILE_PATH" 2>/dev/null; then
+        echo "Validation failed for $ARTIFACT: Invalid JSON" >&2
+        exit 2
+      fi
+    fi
+  fi
+
+  # Update validation.json to mark step as validated (v0.6.0 uses "steps")
+  jq --arg art "$ARTIFACT" '.steps[$art].validated = true' "$VALIDATION_JSON" > "${VALIDATION_JSON}.tmp"
+  mv "${VALIDATION_JSON}.tmp" "$VALIDATION_JSON"
+  echo "✓ Validated: $ARTIFACT.json"
+
+) 200>"$LOCK_FILE"

package/plugins/looplia-core/scripts/hooks/stop-guard.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# Workflow Completion Guard Hook (v0.6.1)
+# Triggered: When main agent attempts to stop
+# Action: Block if any step has validated: false OR output files missing
+
+set -euo pipefail
+
+INPUT=$(cat)
+STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false')
+
+# Prevent infinite loop
+if [[ "$STOP_HOOK_ACTIVE" == "true" ]]; then
+  exit 0
+fi
+
+# Find active sandbox (most recently modified sandbox directory)
+SANDBOX_BASE="${HOME}/.looplia/sandbox"
+if [[ ! -d "$SANDBOX_BASE" ]]; then
+  exit 0
+fi
+
+# Sort by modification time (newest first) to get most recent sandbox
+SANDBOX_DIR=$(ls -td "$SANDBOX_BASE"/*/ 2>/dev/null | head -1 | sed 's:/$::')
+if [[ -z "$SANDBOX_DIR" ]]; then
+  exit 0
+fi
+
+VALIDATION_JSON="$SANDBOX_DIR/validation.json"
+if [[ ! -f "$VALIDATION_JSON" ]]; then
+  exit 0
+fi
+
+# Check for missing output files first (more actionable feedback)
+MISSING=""
+for step in $(jq -r '.steps | keys[]' "$VALIDATION_JSON" 2>/dev/null); do
+  OUTPUT_PATH=$(jq -r --arg s "$step" '.steps[$s].output // empty' "$VALIDATION_JSON" 2>/dev/null)
+  if [[ -n "$OUTPUT_PATH" && ! -f "$OUTPUT_PATH" ]]; then
+    MISSING="$MISSING $step"
+  fi
+done
+
+if [[ -n "$MISSING" ]]; then
+  echo "{\"decision\": \"block\", \"reason\": \"Missing output files for steps:$MISSING. You MUST call the Write tool to create these files at the paths specified in the workflow.\"}"
+  exit 0
+fi
+
+# Check all steps are validated (v0.6.0 uses "steps" not "outputs")
+PENDING=$(jq -r '.steps | to_entries[] | select(.value.validated == false) | .key' "$VALIDATION_JSON" 2>/dev/null | tr '\n' ', ' | sed 's/,$//')
+
+if [[ -n "$PENDING" ]]; then
+  echo "{\"decision\": \"block\", \"reason\": \"Workflow incomplete. Pending validation for steps: $PENDING. Output files exist but need validation - re-write them to trigger validation.\"}"
+  exit 0
+fi
+
+# All validated - allow stop
+exit 0

package/plugins/looplia-core/skills/plugin-registry-scanner/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: plugin-registry-scanner
+description: |
+  This skill should be used when the user wants to discover available looplia skills,
+  scan installed plugins, or list what capabilities are available. Use when someone says
+  "what looplia skills are installed", "list available skills", "scan plugins", "/build",
+  "what can looplia do", or "show me all looplia capabilities".
+
+  First step in looplia workflow building: scans plugins/*/skills/*/SKILL.md to build
+  a registry of available skills. Part of the skills-first architecture where one workflow
+  step invokes one skill-executor to orchestrate multiple skills.
+tools: Bash, Read, Glob
+model: claude-haiku-4-5-20251001
+---
+
+# Plugin Registry Scanner
+
+Discover and catalog all skills from installed looplia plugins.
+
+## Purpose
+
+Scan the `plugins/*/skills/*/SKILL.md` directory structure to build a registry of available skills with their capabilities.
+
+## Process
+
+### 1. Scan Plugin Directories
+
+```bash
+bun plugins/looplia-core/skills/plugin-registry-scanner/scripts/scan-plugins.ts
+```
+
+This deterministic script returns a JSON registry of all discovered skills.
+
+### 2. Parse the Registry
+
+The script output contains:
+
+```json
+{
+  "plugins": [
+    {
+      "name": "looplia-writer",
+      "path": "plugins/looplia-writer",
+      "skills": [
+        {
+          "name": "media-reviewer",
+          "description": "Deep content analysis (structure, themes, narrative)",
+          "tools": ["Read", "Grep", "Glob"],
+          "model": "haiku",
+          "capabilities": ["content analysis", "theme extraction", "quote identification"]
+        }
+      ]
+    }
+  ],
+  "summary": {
+    "totalPlugins": 2,
+    "totalSkills": 7
+  }
+}
+```
+
+### 3. Infer Capabilities (Optional LLM Step)
+
+If capability inference is needed beyond what the script provides, analyze skill descriptions to extract:
+- Input types handled (video, audio, text, etc.)
+- Processing capabilities (analyze, transform, generate, etc.)
+- Output formats (JSON, markdown, structured data)
+
+## Output Schema
+
+```json
+{
+  "plugins": [
+    {
+      "name": "string",
+      "path": "string",
+      "skills": [
+        {
+          "name": "string",
+          "description": "string",
+          "tools": ["string"],
+          "model": "string",
+          "capabilities": ["string"]
+        }
+      ]
+    }
+  ],
+  "summary": {
+    "totalPlugins": "number",
+    "totalSkills": "number"
+  }
+}
+```
+
+## Usage
+
+This skill is typically invoked as the first step in workflow building:
+
+1. Scan available plugins and skills
+2. Pass registry to skill-capability-matcher
+3. Use matched skills in workflow-schema-composer
+
+## Notes
+
+- The scan script is deterministic (no LLM tokens)
+- Capabilities can be inferred from descriptions if not explicitly declared
+- Skills without SKILL.md files are skipped
+- Invalid frontmatter generates warnings but doesn't halt scanning