Skip to content

01-getting-started.md

Latest commit

 

History

History
231 lines (178 loc) · 8.7 KB

01-getting-started.md

File metadata and controls

231 lines (178 loc) · 8.7 KB
layout title nav_order parent
default
Chapter 1: Getting Started
1
Compound Engineering Plugin Tutorial

Chapter 1: Getting Started

Welcome to Chapter 1: Getting Started. In this part of Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.

This chapter gets the compound-engineering plugin installed and running in Claude Code.

Learning Goals

  • add the marketplace and install compound-engineering
  • run the core workflow commands at least once
  • verify generated behaviors align to documented flow
  • understand initial setup requirements for team rollout

Install Commands

/plugin marketplace add https://github.com/EveryInc/compound-engineering-plugin
/plugin install compound-engineering

First-Run Validation

  • run /workflows:plan on a small feature request
  • run /workflows:work for scoped implementation
  • run /workflows:review and inspect findings
  • run /workflows:compound to capture reusable learnings

Source References

Summary

You now have a working compound-engineering baseline in Claude Code.

Next: Chapter 2: Compound Engineering Philosophy and Workflow Loop

Depth Expansion Playbook

Source Code Walkthrough

src/commands/install.ts

The resolvePluginPath function in src/commands/install.ts handles a key part of this chapter's functionality:

    }

    const resolvedPlugin = await resolvePluginPath(String(args.plugin))

    try {
      const plugin = await loadClaudePlugin(resolvedPlugin.path)
      const outputRoot = resolveOutputRoot(args.output)
      const codexHome = resolveTargetHome(args.codexHome, path.join(os.homedir(), ".codex"))
      const piHome = resolveTargetHome(args.piHome, path.join(os.homedir(), ".pi", "agent"))
      const hasExplicitOutput = Boolean(args.output && String(args.output).trim())
      const openclawHome = resolveTargetHome(args.openclawHome, path.join(os.homedir(), ".openclaw", "extensions"))
      const qwenHome = resolveTargetHome(args.qwenHome, path.join(os.homedir(), ".qwen", "extensions"))

      const options = {
        agentMode: String(args.agentMode) === "primary" ? "primary" : "subagent",
        inferTemperature: Boolean(args.inferTemperature),
        permissions: permissions as PermissionMode,
      }

      if (targetName === "all") {
        const detected = await detectInstalledTools()
        const activeTargets = detected.filter((t) => t.detected)

        if (activeTargets.length === 0) {
          console.log("No AI coding tools detected. Install at least one tool first.")
          return
        }

        console.log(`Detected ${activeTargets.length} tool(s):`)
        for (const tool of detected) {
          console.log(`  ${tool.detected ? "✓" : "✗"} ${tool.name} — ${tool.reason}`)
        }

This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.

src/commands/install.ts

The parseExtraTargets function in src/commands/install.ts handles a key part of this chapter's functionality:

      console.log(`Installed ${plugin.manifest.name} to ${primaryOutputRoot}`)

      const extraTargets = parseExtraTargets(args.also)
      const allTargets = [targetName, ...extraTargets]
      for (const extra of extraTargets) {
        const handler = targets[extra]
        if (!handler) {
          console.warn(`Skipping unknown target: ${extra}`)
          continue
        }
        if (!handler.implemented) {
          console.warn(`Skipping ${extra}: not implemented yet.`)
          continue
        }
        const extraBundle = handler.convert(plugin, options)
        if (!extraBundle) {
          console.warn(`Skipping ${extra}: no output returned.`)
          continue
        }
        const extraRoot = resolveTargetOutputRoot({
          targetName: extra,
          outputRoot: path.join(outputRoot, extra),
          codexHome,
          piHome,
          openclawHome,
          qwenHome,
          pluginName: plugin.manifest.name,
          hasExplicitOutput,
          scope: handler.defaultScope,
        })
        await handler.write(extraRoot, extraBundle, handler.defaultScope)
        console.log(`Installed ${plugin.manifest.name} to ${extraRoot}`)

This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.

src/commands/install.ts

The resolveOutputRoot function in src/commands/install.ts handles a key part of this chapter's functionality:

    try {
      const plugin = await loadClaudePlugin(resolvedPlugin.path)
      const outputRoot = resolveOutputRoot(args.output)
      const codexHome = resolveTargetHome(args.codexHome, path.join(os.homedir(), ".codex"))
      const piHome = resolveTargetHome(args.piHome, path.join(os.homedir(), ".pi", "agent"))
      const hasExplicitOutput = Boolean(args.output && String(args.output).trim())
      const openclawHome = resolveTargetHome(args.openclawHome, path.join(os.homedir(), ".openclaw", "extensions"))
      const qwenHome = resolveTargetHome(args.qwenHome, path.join(os.homedir(), ".qwen", "extensions"))

      const options = {
        agentMode: String(args.agentMode) === "primary" ? "primary" : "subagent",
        inferTemperature: Boolean(args.inferTemperature),
        permissions: permissions as PermissionMode,
      }

      if (targetName === "all") {
        const detected = await detectInstalledTools()
        const activeTargets = detected.filter((t) => t.detected)

        if (activeTargets.length === 0) {
          console.log("No AI coding tools detected. Install at least one tool first.")
          return
        }

        console.log(`Detected ${activeTargets.length} tool(s):`)
        for (const tool of detected) {
          console.log(`  ${tool.detected ? "✓" : "✗"} ${tool.name} — ${tool.reason}`)
        }

        for (const tool of activeTargets) {
          const handler = targets[tool.name]
          if (!handler || !handler.implemented) {

This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.

src/commands/install.ts

The resolveGitHubPluginPath function in src/commands/install.ts handles a key part of this chapter's functionality:

  // Otherwise, always fetch the latest from GitHub
  return await resolveGitHubPluginPath(input)
}

function parseExtraTargets(value: unknown): string[] {
  if (!value) return []
  return String(value)
    .split(",")
    .map((entry) => entry.trim())
    .filter(Boolean)
}

function resolveOutputRoot(value: unknown): string {
  if (value && String(value).trim()) {
    const expanded = expandHome(String(value).trim())
    return path.resolve(expanded)
  }
  // OpenCode global config lives at ~/.config/opencode per XDG spec
  // See: https://opencode.ai/docs/config/
  return path.join(os.homedir(), ".config", "opencode")
}

async function resolveGitHubPluginPath(pluginName: string): Promise<ResolvedPluginPath> {
  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "compound-plugin-"))
  const source = resolveGitHubSource()
  try {
    await cloneGitHubRepo(source, tempRoot)
  } catch (error) {
    await fs.rm(tempRoot, { recursive: true, force: true })
    throw error
  }

This function is important because it defines how Compound Engineering Plugin Tutorial: Compounding Agent Workflows Across Toolchains implements the patterns covered in this chapter.

How These Components Connect

flowchart TD
    A[resolvePluginPath]
    B[parseExtraTargets]
    C[resolveOutputRoot]
    D[resolveGitHubPluginPath]
    E[resolveGitHubSource]
    A --> B
    B --> C
    C --> D
    D --> E
Loading