How Workflow Commands Implement Compound Engineering in the EveryInc Plugin

Workflow commands implement compound engineering through a declarative three‑layer architecture where markdown files define commands, a plugin manifest exposes them to Claude Code, and runtime converters translate slash commands into platform‑specific agent orchestration.

The EveryInc/compound-engineering-plugin demonstrates how workflow commands implement compound engineering by transforming simple slash commands like /workflows:plan into complex, multi‑agent automation. This open‑source plugin uses a declarative architecture that separates command definition from execution logic, enabling version‑controlled engineering workflows that run across multiple AI agent platforms.

Declarative Command Definition in Markdown

Anatomy of a Workflow Command File

Each workflow command lives as a standalone markdown file inside plugins/compound-engineering/commands/workflows/. The file uses YAML front‑matter to declare metadata and a markdown body to define agent orchestration logic.

In plugins/compound-engineering/commands/workflows/plan.md, the front‑matter declares the command name, description, and expected arguments:

---
name: workflows:plan
description: Transform feature descriptions into well‑structured project plans
argument-hint: "[feature description, bug report, or improvement idea]"
---

The name: field creates the slash command /workflows:plan that users invoke in Claude Code.

Plugin Manifest and Command Discovery

The plugin.json Manifest

The file .claude-plugin/plugin.json serves as the plugin’s entry point. It tells the Claude Code runtime that the directory contains executable commands and provides metadata such as version and description.

{
  "name": "compound-engineering",
  "version": "1.0.0",
  "description": "Compound engineering workflows with 5 workflow commands",
  "type": "commands"
}

When the plugin is installed, the runtime scans the commands/ directory, parses every markdown file with a name: key in its front‑matter, and registers the corresponding slash commands.

Runtime Registration

The CLI loader uses a glob pattern to discover command files and extract their front‑matter:

// In the command loader (simplified)
for (const file of globSync('plugins/**/commands/**/*.md')) {
  const front = parseFrontmatter(file);
  if (front.name) registerSlashCommand(front.name, file);
}

This registration process exposes /workflows:plan, /workflows:work, /workflows:review, /workflows:brainstorm, and /workflows:compound to the user.

Runtime Conversion and Cross‑Platform Execution

Namespace Preservation Across Agents

The plugin’s runtime converters translate Claude‑style slash commands into the specific syntax required by different AI agents (PI, Droid, Cursor, Codex, Gemini). The converters preserve the workflows: namespace to ensure correct routing, flattening it only for platforms that lack namespace support.

In src/converters/claude-to-pi.ts, the conversion logic handles the namespace:

// src/converters/claude-to-pi.ts
// /command-name or /workflows:command-name -> /workflows-command-name
if (cmd.startsWith('workflows:')) {
  piCmd = `workflows-${cmd.slice('workflows:'.length)}`;
}

Similar logic appears in src/converters/claude-to-droid.ts and other converter files, ensuring consistent behavior across platforms.

Supported Target Platforms

The converter layer supports multiple agent runtimes:

• PI: Flattens workflows:plan to workflows-plan
• Droid: Preserves structure with platform‑specific prefixes
• Cursor/Codex/Gemini: Adapts syntax while maintaining the workflow namespace semantics

This abstraction allows the compound engineering plugin to run identical workflow commands across heterogeneous AI environments.

Agent Orchestration and Parallel Execution

Defining Parallel Agent Tasks

The markdown body of each workflow command contains agent tasks that the runtime launches in parallel. These tasks define the actual work performed when a user invokes the command.

In plugins/compound-engineering/commands/workflows/plan.md, the body defines parallel research agents:

Run these agents **in parallel** to gather local context:

- Task repo-research-analyst(feature_description)
- Task learnings-researcher(feature_description)

When /workflows:plan executes, the runtime spawns both agents simultaneously, waits for their results, and synthesizes the output into a structured project plan. This orchestration pattern turns simple slash commands into compound engineering workflows that coordinate multiple AI agents.

Testing and Validation

Unit Test Coverage

The test suite verifies that the parser discovers each workflow command and that conversion logic produces expected output for every target platform. This ensures commands remain available and correctly namespaced across releases.

In tests/claude-parser.test.ts, tests validate specific workflow commands:

test('parses workflow commands', () => {
  const plugin = parsePlugin('plugins/compound-engineering');
  const review = plugin.commands.find(c => c.name === 'workflows:review');
  expect(review).toBeDefined();
  const work = plugin.commands.find(c => c.name === 'workflows:work');
  expect(work).toBeDefined();
});

These tests guarantee that workflow commands implementing compound engineering are correctly parsed from their markdown definitions and exposed to the runtime.

Summary

• Declarative definition: Workflow commands are defined as markdown files with YAML front‑matter in plugins/compound-engineering/commands/workflows/, making them version‑controlled and easy to extend.
• Automatic discovery: The .claude-plugin/plugin.json manifest enables the runtime to scan and register commands like /workflows:plan without manual configuration.
• Cross‑platform execution: Converters in src/converters/ translate Claude slash commands to PI, Droid, Cursor, and other agent formats while preserving the workflows: namespace.
• Agent orchestration: Command bodies define parallel agent tasks (e.g., Task repo-research-analyst()) that implement compound engineering by coordinating multiple AI agents simultaneously.
• Test coverage: Unit tests in tests/claude-parser.test.ts ensure workflow commands are correctly discovered and converted across all supported platforms.

Frequently Asked Questions

How do workflow commands implement compound engineering differently from simple slash commands?

Workflow commands implement compound engineering by acting as orchestrators rather than single operations. While simple slash commands execute one function, workflow commands like /workflows:plan defined in plugins/compound-engineering/commands/workflows/plan.md spawn multiple specialized agents (e.g., repo-research-analyst and learnings-researcher) in parallel. This multi-agent coordination transforms a single user command into a complex engineering workflow that gathers context, analyzes requirements, and synthesizes deliverables simultaneously.

What is the purpose of the YAML front‑matter in workflow command files?

The YAML front‑matter serves as the declarative interface that makes workflow commands discoverable and executable. Each markdown file in plugins/compound-engineering/commands/workflows/ contains front‑matter fields like name: workflows:plan, description, and argument-hint that define the command signature. The CLI loader parses this metadata to register the command with the Claude Code runtime, enabling users to invoke /workflows:plan without any imperative configuration code.

How does the plugin ensure workflow commands work across different AI platforms?

The plugin ensures cross‑platform compatibility through a converter layer located in src/converters/. Files like claude-to-pi.ts and claude-to-droid.ts map Claude's slash command syntax to platform‑specific formats. For example, the converter transforms workflows:plan into workflows-plan for PI agents while preserving the semantic namespace. This abstraction layer allows the same markdown command definitions to execute correctly on PI, Droid, Cursor, Codex, and Gemini without modifying the source command files.

Where are the workflow commands tested to ensure reliability?

Workflow commands are validated in tests/claude-parser.test.ts, which contains unit tests that verify command discovery and parsing. The test suite checks that the parser correctly identifies specific workflow commands like workflows:review and workflows:work from the plugin directory structure. These tests ensure that the declarative definitions in plugins/compound-engineering/commands/workflows/ are correctly registered and remain available across plugin updates, providing a safety net for the compound engineering automation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}