Workflow Packages

Workflow packages are the standard format for distributing pre-built workflows in Syntropic137. After running npx syntropic137 setup, installing a workflow package is the fastest way to start doing useful work with the platform.

Quick Start

# Install the starter research workflow
syn workflow install ./workflows/examples/research-package/

# Run it
syn workflow run research-package-v1 --task "Investigate event sourcing patterns for our platform"

# See what's installed
syn workflow installed

Installing Packages

Workflow packages can be installed from local directories or git repositories:

# Local directory
syn workflow install ./my-package/

# GitHub repository
syn workflow install https://github.com/org/workflow-library
syn workflow install org/workflow-library              # Shorthand
syn workflow install org/workflow-library --ref v2.0   # Specific version

# Validate before installing
syn workflow install ./my-package/ --dry-run

The install command resolves all prompt files and shared phases, then creates each workflow via the API. Installed packages are tracked locally in ~/.syntropic137/workflows/installed.json.

Package Formats

Single Workflow

The simplest format — one workflow with its phase prompts:

Multi-Workflow Plugin

Bundle multiple workflows with a shared phase library:

Shared phases are referenced with the shared:// prefix:

phases:
  - id: summarize
    prompt_file: shared://summarize  # → phase-library/summarize.md

Content is resolved at install time — no runtime dependency on the library.

Creating Packages

Scaffold from Template

# Single workflow
syn workflow init ./my-workflow --name "My Workflow" --type research --phases 3

# Multi-workflow plugin
syn workflow init ./my-plugin --name "My Plugin" --multi

Phase Prompt Files

Phase prompts use optional YAML frontmatter followed by the prompt body:

---
model: sonnet
argument-hint: "[topic]"
allowed-tools: Read,Glob,Grep,Bash
max-tokens: 4096
timeout-seconds: 300
---

You are a research assistant investigating: $ARGUMENTS

Use {{discovery}} to reference output from a previous phase.

Frontmatter provides defaults; workflow.yaml values always take precedence.

Plugin Manifest

Multi-workflow plugins use syntropic137-plugin.json for metadata:

{
  "manifest_version": 1,
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Research and review workflows",
  "author": "my-org",
  "license": "MIT"
}

Exporting Workflows

Export a running workflow from Syntropic137 as a distributable plugin. Exported plugins can be re-imported on another instance or shared via a marketplace.

# Export as a package (workflow.yaml + phase .md files)
syn workflow export <workflow-id> --output ./my-package/

# Export as a plugin (includes CC command wrapper for slash-command invocation)
syn workflow export <workflow-id> --format plugin --output ./my-plugin/

Package Format (default)

Produces a directory that can be re-installed with syn workflow install:

Plugin Format

Produces a Syntropic137 plugin with a manifest, CC command wrapper, and workflow:

The commands/syn-*.md wrapper calls syn workflow run, so the exported workflow can also be invoked as a /syn-* slash command from Claude Code. The package itself is a Syntropic137 plugin — the CC command is a convenience bridge.

Round-Trip Guarantee

Exported packages are always re-importable:

syn workflow export my-workflow-v1 --output ./exported/
syn workflow install ./exported/   # produces an equivalent workflow

Validating Packages

# Validate a package directory
syn workflow validate ./my-package/

# Validate a single YAML file
syn workflow validate ./workflow.yaml

Validation checks the YAML schema, verifies that all referenced .md files exist, and resolves shared:// references.

Example Packages

The repository includes reference implementations:

• workflows/examples/research-package/ — Single workflow with discovery + synthesis phases
• workflows/examples/starter-plugin/ — Multi-workflow plugin with shared summarize phase

Marketplace

The marketplace lets you discover, install, and share workflow plugins from GitHub-hosted registries. Any GitHub repository with a marketplace.json at the root can serve as a marketplace.

Register a Marketplace

# Add the official Syntropic137 marketplace
syn marketplace add syntropic137/workflow-library

# Add a company-internal marketplace
syn marketplace add myorg/internal-workflows --name my-company

# Add from a specific branch or tag
syn marketplace add myorg/workflows --ref v2.0

# List registered marketplaces
syn marketplace list

# Refresh cached indexes
syn marketplace refresh

# Refresh a specific marketplace
syn marketplace refresh my-company

# Remove a marketplace
syn marketplace remove my-company

Discover Workflows

# Search across all registered marketplaces
syn workflow search "research"
syn workflow search --category research
syn workflow search --tag multi-phase

# Show details of a specific plugin
syn workflow info research-toolkit

Search matches against plugin name, description, category, and tags (case-insensitive). An empty query returns all plugins across all registries.

Install from Marketplace

# Install by plugin name (resolved from registered marketplaces)
syn workflow install research-toolkit

# Still works: install from local paths and git URLs
syn workflow install ./my-package/
syn workflow install org/repo

When you pass a bare name (no slashes, not a path), the CLI checks registered marketplaces first. If found, it clones the marketplace repo, resolves the plugin's subdirectory, and installs the workflows.

Update and Uninstall

# Update a package to the latest version
syn workflow update research-toolkit

# Check for updates without applying
syn workflow update research-toolkit --dry-run

# Uninstall (removes workflows from the platform)
syn workflow uninstall research-toolkit

# Uninstall but keep workflows running
syn workflow uninstall research-toolkit --keep-workflows

Updates compare the remote git SHA against the installed SHA. If they match, the package is already up to date and no action is taken.

Creating a Marketplace Repository

Any GitHub repository can be a marketplace. Create a marketplace.json at the root and organize plugins in subdirectories:

Step 1: Create the Repository Structure

Step 2: Write marketplace.json

{
  "name": "my-marketplace",
  "syntropic137": {
    "type": "workflow-marketplace"
  },
  "plugins": [
    {
      "name": "research-toolkit",
      "source": "./plugins/research-toolkit",
      "version": "1.2.0",
      "description": "Deep research and quick-scan workflows",
      "category": "research",
      "tags": ["multi-phase", "deep-dive", "synthesis"]
    },
    {
      "name": "pr-automation",
      "source": "./plugins/pr-automation",
      "version": "0.5.0",
      "description": "Automated PR review and feedback",
      "category": "ci",
      "tags": ["github", "code-review"]
    }
  ]
}

Step 3: Push and Register

git push origin main

# Users register your marketplace:
syn marketplace add your-org/my-marketplace

marketplace.json Schema

The marketplace.json file is the index that describes all plugins in the marketplace. It must be a JSON object at the repository root.

Each plugin entry in the plugins array:

The source path must be relative (no absolute paths or .. traversal). Each plugin directory follows the standard package format — either a single workflow or a multi-workflow plugin.

Caching and Refresh

Marketplace indexes are cached locally at ~/.syntropic137/marketplace/cache/ to avoid cloning on every search or install.

• Cache TTL: 4 hours. After this, the next search or install re-fetches the index.
• Force refresh: syn marketplace refresh bypasses the TTL and fetches fresh indexes.
• Cache location: ~/.syntropic137/marketplace/cache/<registry-name>.json
• Registry config: ~/.syntropic137/registries.json

Searches and plugin lookups use the cache when fresh, falling back to a fresh fetch when stale. If a fetch fails (network error, repo not found), stale cache entries are skipped silently.

Private Marketplaces

Private GitHub repositories work as marketplaces if git can authenticate. The CLI uses your local git credential configuration — no special flags needed.

# Ensure git can access the private repo (any of these work):
# - GitHub CLI: gh auth login
# - SSH key: git clone git@github.com:myorg/private-marketplace.git
# - Credential helper: git config credential.helper

# Then register normally:
syn marketplace add myorg/private-marketplace --name internal

For CI environments, set the GIT_ASKPASS or GH_TOKEN environment variable, or configure a credential helper that reads from environment variables.

Troubleshooting

"No marketplace.json found in repo" — The repository must have a marketplace.json at the root of the default branch (or the branch specified with --ref).

"syntropic137.type must be 'workflow-marketplace'" — The syntropic137 key in marketplace.json must contain "type": "workflow-marketplace". This marker distinguishes marketplace repos from other Syntropic137 content.

"Invalid registry name" — Registry names must start with an alphanumeric character and contain only letters, digits, hyphens, underscores, and dots. Names like ../evil or my/registry are rejected.

Plugin not found after registering — Run syn marketplace refresh to re-fetch the latest index. The local cache may be stale.

Private repo access denied — Ensure git clone works for the repo URL from your terminal. The CLI uses the same git credentials as your shell.

"Package is already up to date" — syn workflow update compares git SHAs. If the remote HEAD hasn't changed, no update is needed.

Limitations

• One marketplace index per repository (no nested marketplace files)
• No dependency resolution between plugins
• No version conflict detection across multiple marketplaces
• No rollback to a previous plugin version (uninstall and re-install at a pinned --ref)
• Search is substring-based, not fuzzy or ranked

Learn More

• CLI Reference — all syn workflow and syn marketplace commands
• API Reference — workflow creation endpoints