agentcmd-workflows SDK

npm install agentcmd-workflows inngest

import { defineWorkflow } from "agentcmd-workflows";

export default defineWorkflow(
  {
    id: "my-workflow",
    name: "My First Workflow",
    phases: ["plan", "execute"] as const,
  },
  async ({ event, step }) => {
    await step.phase("plan", async () => {
      await step.agent("analyze", {
        agent: "claude",
        prompt: "Analyze the codebase structure",
      });
    });

    await step.phase("execute", async () => {
      await step.cli("build", { command: "npm run build" });
    });
  }
);

npx agentcmd-workflows init [path]

npx agentcmd-workflows generate-slash-types \
  --input .claude/commands \
  --output .agent/generated/slash-commands.ts

your-project/
├── .agent/
│   ├── workflows/
│   │   └── definitions/          # Your workflow files
│   │       └── implement-review-workflow.ts
│   ├── specs/
│   │   ├── backlog/              # Future work
│   │   ├── todo/                 # Current sprint
│   │   ├── done/                 # Completed specs
│   │   └── index.json            # Spec registry
│   ├── generated/
│   │   └── slash-commands.ts     # Auto-generated types
│   └── logs/                     # Execution logs
│
├── .claude/
│   └── commands/
│       └── cmd/                  # Slash command definitions
│           ├── generate-spec.md
│           ├── implement-spec.md
│           └── ... (12 total)

import { defineWorkflow } from "agentcmd-workflows";

export default defineWorkflow(config, handler);

import { defineSchema, type InferSchemaType } from "agentcmd-workflows";

const argsSchema = defineSchema({
  type: "object",
  properties: {
    featureName: { type: "string" },
    priority: { enum: ["high", "medium", "low"] },
  },
  required: ["featureName"],
});

type Args = InferSchemaType<typeof argsSchema>;
// Result: { featureName: string; priority?: "high" | "medium" | "low" }

interface WorkflowConfig {
  id: string;                           // Unique identifier (required)
  name?: string;                        // Human-readable name
  description?: string;                 // Workflow description
  phases?: readonly PhaseDefinition[];  // Phase organization
  timeout?: number;                     // Global timeout in ms
  argsSchema?: JSONSchema;              // Input validation + type inference
}

const argsSchema = defineSchema({
  type: "object",
  properties: {
    specFile: { type: "string" },
    dryRun: { type: "boolean" },
  },
  required: ["specFile"],
});

export default defineWorkflow(
  { id: "impl", argsSchema },
  async ({ event }) => {
    // event.data.args is fully typed
    const { specFile, dryRun } = event.data.args;
  }
);

---
description: "My custom command description"
argument-hint: [requiredArg, (optionalArg)]
---

# My Command

Command instructions for Claude...

## JSON Output

<json_output>
{
  "success": true,
  "message": "Result message"
}
</json_output>

// Union of all command names
export type SlashCommandName = "/cmd:generate-spec" | "/cmd:implement-spec" | ...;

// Args interface per command
export interface CmdImplementSpecArgs {
  specIdOrNameOrPath: string;
}

// Response interface per command
export interface CmdImplementSpecResponse {
  success: boolean;
  message: string;
}

// Type-safe command builder
export function buildSlashCommand<T extends SlashCommandName>(
  name: T,
  args?: SlashCommandArgs[T]
): string;

import {
  buildSlashCommand,
  type CmdImplementSpecResponse,
} from "../generated/slash-commands";

await step.agent<CmdImplementSpecResponse>("implement", {
  agent: "claude",
  json: true,
  prompt: buildSlashCommand("/cmd:implement-spec", {
    specIdOrNameOrPath: "feature-auth",
  }),
});

await step.agent("long-task", { ... }, { timeout: 3600000 }); // 1 hour

export default defineWorkflow(config, async ({ event, step }) => {
  interface Context {
    specFile?: string;
    prUrl?: string;
  }
  const ctx: Context = {};

  await step.phase("generate", async () => {
    const result = await step.agent("gen-spec", { ... });
    ctx.specFile = result.data.spec_file;
  });

  await step.phase("implement", async () => {
    // Access ctx.specFile from previous phase
    await step.agent("impl", {
      prompt: `Implement ${ctx.specFile}`,
    });
  });
});

const MAX_ATTEMPTS = 10;

await step.phase("implement", async () => {
  for (let i = 1; i <= MAX_ATTEMPTS; i++) {
    const result = await step.agent<CmdImplementSpecResponse>(
      `implement-${i}`,  // Unique step ID per attempt
      {
        agent: "claude",
        json: true,
        prompt: buildSlashCommand("/cmd:implement-spec", { ... }),
      }
    );

    if (result.data.success) return;
  }
  throw new Error("Max attempts exceeded");
});

await step.phase("deploy", async () => {
  const testResult = await step.cli("test", { command: "npm test" });

  if (testResult.data.exitCode === 0) {
    await step.cli("deploy", { command: "npm run deploy" });
    await step.annotation("deployed", { message: "Deployment successful" });
  } else {
    await step.annotation("skipped", { message: "Tests failed, skipping deploy" });
  }
});