workflow-schema Documentation

Official TypeScript developer resources and documentation for breaking-brake/workflow-schema. Verified technical context for AI.

0 stars TypeScript TypeScript 1 file · ~5,623 tokens
RAW Doc

1. Project Overview & Quickstart (breaking-brake/workflow-schema)

workflow-schema

Open-source repository breaking-brake/workflow-schema

Repository Details

Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.

2. Official Technical Reference & Guides (breaking-brake/breaking-brake.github.io)

File: README.md

Claude Code Workflow Studio 開発ブログ

このリポジトリは、Claude Code Workflow Studio プロジェクトの開発に関する情報を発信するブログサイトです。

📖 About

Claude Code Workflow Studio は、AI エージェントのワークフローをビジュアルに設計できる VSCode 拡張機能です。ドラッグ&ドロップでノードを配置し、Claude Code の .claude 形式にエクスポートすることで、プログラミング知識なしで高度な自動化フローを構築できます。

このブログでは、以下の情報を発信しています：

  • 🎯 プロジェクト紹介: 機能概要とビジョン
  • 🚀 クイックスタート: 導入方法と基本的な使い方
  • 💡 ユースケース: データ分析、コードレビューなど実践的な活用例
  • ❓ FAQ: よくある質問と回答

🔗 関連リンク

🛠️ 技術スタック

このブログサイトは以下の技術を使用して構築されています：

  • Astro: 高速な静的サイトジェネレーター
  • TypeScript: 型安全性の向上
  • Biome: コードフォーマッター＆リンター
  • GitHub Actions: 自動デプロイ

🚀 開発

セットアップ

bash
# リポジトリのクローン
git clone https://github.com/breaking-brake/breaking-brake.github.io.git
cd breaking-brake.github.io

# 依存関係のインストール
npm install

# 開発サーバーの起動
npm run dev

ブラウザで http://localhost:4321 を開いてサイトを確認できます。

利用可能なコマンド

コマンド 説明
npm run dev 開発サーバーを起動（localhost:4321）
npm run build 本番用サイトを ./dist/ にビルド
npm run preview ビルドしたサイトをローカルでプレビュー
npm run check Biome によるコード品質チェック
npm run format コードの自動フォーマット
npm run lint Lint チェック
npm run lint:fix Lint 問題の自動修正

📝 ブログ記事の追加

新しい記事を追加する手順：

  1. src/content/blog/ に新しいマークダウンファイルを作成（例: 006-new-article.md）

  2. Frontmatter（YAML）形式でメタデータを記述：

markdown
---
title: "記事のタイトル"
pubDate: 2024-02-10
author: "著者名"
---

ここに記事の本文を記述します...
  1. 開発サーバーで確認：
bash
npm run dev
  1. 確認後、コミットしてプッシュ：
bash
git add src/content/blog/006-new-article.md
git commit -m "feat: Add new blog article"
git push

🗂️ プロジェクト構造

text
breaking-brake.github.io/
├── .github/
│   └── workflows/
│       └── deploy.yml          # GitHub Pages 自動デプロイ
├── src/
│   ├── components/
│   │   ├── Header.astro        # ヘッダーコンポーネント
│   │   └── Footer.astro        # フッターコンポーネント
│   ├── layouts/
│   │   ├── Layout.astro        # 基本レイアウト
│   │   └── BlogLayout.astro    # ブログ記事用レイアウト
│   ├── pages/
│   │   ├── index.astro         # トップページ
│   │   ├── about.astro         # 概要ページ
│   │   └── blog/
│   │       └── [...slug].astro # 動的ブログページ
│   └── content/
│       ├── config.ts           # コンテンツコレクション設定
│       └── blog/               # ブログ記事（Markdown）
│           ├── 001-cc-wf-studio-intro.md
│           ├── 002-quick-start-tutorial.md
│           ├── 003-usecase-data-analysis.md
│           ├── 004-usecase-code-review.md
│           └── 005-faq.md
├── public/                     # 静的ファイル
├── astro.config.mjs            # Astro 設定
├── biome.json                  # Biome 設定
├── tsconfig.json               # TypeScript 設定
└── package.json                # 依存関係

🚢 デプロイ

このサイトは GitHub Actions を使用して自動的にデプロイされます。

自動デプロイ

main ブランチへのプッシュ時に自動的にビルドとデプロイが実行されます。

手動デプロイ

GitHub Actions タブから「Deploy to GitHub Pages」ワークフローを手動実行することもできます。

🤝 コントリビューション

コントリビューションを歓迎します！以下の手順でご協力ください：

  1. このリポジトリをフォーク
  2. 新しいブランチを作成 (git checkout -b feature/amazing-article)
  3. 変更をコミット (git commit -m 'feat: Add amazing article')
  4. ブランチにプッシュ (git push origin feature/amazing-article)
  5. Pull Request を作成

詳細は CONTRIBUTING.md をご覧ください。

📄 ライセンス

このプロジェクトは MIT License の下で公開されています。詳細は LICENSE をご覧ください。

📞 サポート

⭐ Claude Code Workflow Studio に興味を持たれた方は、本体リポジトリ もぜひご覧ください！

File: docs/docs/edit-with-ai.md

Edit with AI

CC Workflow Studio ships with an MCP server (cc-workflow-ai-editor) that exposes the canvas to external AI agents. Click an agent button in the Edit with AI panel and the server starts in the background — the agent can then read the current workflow, modify nodes, and apply changes back to the canvas in a loop.

mermaid
sequenceDiagram
    actor User
    participant UI as Editor UI
    participant MCP as MCP Server
    participant Agent as AI Agent

    User->>UI: Click agent button
    UI->>MCP: Auto start server
    UI->>Agent: Launch with editing skill

    loop AI edits workflow
        Agent->>MCP: get_current_workflow
        MCP-->>Agent: workflow JSON
        Agent->>MCP: apply_workflow
        MCP->>UI: Update canvas
    end

MCP tools

Tool Purpose
get_current_workflow Get the workflow currently on the canvas.
get_workflow_schema Get the workflow schema (TOON-formatted).
apply_workflow Replace the canvas with a new workflow JSON after validation.
list_available_agents List .claude/agents/*.md files (user + project scopes).
update_nodes Patch specific nodes by ID without resending the whole workflow.

Typical loop

An agent usually does something like:

  1. get_workflow_schema once, to learn the valid shape
  2. get_current_workflow to read what's on the canvas and capture the revision number
  3. Decide what to change
  4. update_nodes for partial edits, or apply_workflow for full replacements
  5. Repeat from step 2 for the next iteration

If the user has review mode enabled, apply_workflow and update_nodes show a diff dialog. Rejections come back as an error with the message User rejected the changes.

`get_current_workflow`

No input. Returns the workflow JSON, its revision number (used for conflict detection), and an isStale flag that is true when the editor is closed and the workflow came from cache.

json
{
  "success": true,
  "isStale": false,
  "revision": 42,
  "workflow": { "schemaVersion": "1.0.0", "name": "…", "nodes": [...], "edges": [...] }
}

`get_workflow_schema`

No input. Returns the schema as TOON-formatted text (compact, token-efficient). Use it before generating or editing a workflow so the model knows the valid node types and field constraints.

`apply_workflow`

Input:

json
{
  "workflow": "{\"schemaVersion\":\"1.0.0\",\"name\":\"…\",\"nodes\":[…],\"edges\":[…]}",
  "description": "Added error handling step after API call",
  "revision": 42
}
  • workflow — the full workflow JSON, as a string
  • description (optional) — shown to the user in the review dialog
  • revision (optional) — if provided and the canvas has moved on, the apply is rejected or a warning is shown

SubAgent nodes without a commandFilePath will have .md files auto-created under .claude/agents/.

`update_nodes`

Apply partial edits without resending the whole workflow.

Input:

json
{
  "nodes": [
    {
      "id": "node-3",
      "name": "Summarize results",
      "data": { "prompt": "…updated prompt…" }
    },
    {
      "id": "node-5",
      "position": { "x": 600, "y": 240 }
    }
  ],
  "description": "Renamed summary step and moved layout",
  "revision": 42
}

Each entry must include id and at least one of name, position, data, type, parentId, or style.

  • data is shallow-merged, not replaced. Set a field to null to delete it: { "commandFilePath": null }
  • type changes require a new data object (fully replaces the old one)
  • Only existing nodes are updated — use apply_workflow to add or remove nodes

`list_available_agents`

Input:

json
{ "includeContent": false }

Returns agent definition files from ~/.claude/agents/ and project-level .claude/agents/:

json
{
  "success": true,
  "totalCount": 7,
  "userCount": 3,
  "projectCount": 4,
  "commands": [
    { "name": "code-reviewer", "description": "…", "scope": "project", "commandPath": ".claude/agents/code-reviewer.md" }
  ]
}

Set includeContent to true to include the full prompt body of each file.

Configuration

Setting Default Purpose
cc-wf-studio.mcp.port 6282 Port the embedded MCP server listens on
cc-wf-studio.ai.schemaFormat toon Format returned by get_workflow_schema

See also: Workflow JSON Schema for the shape of the workflow data the tools operate on.

File: docs/docs/index.md

Overview

Everything you need to get productive with CC Workflow Studio.

File: docs/docs/installation.md

Installation

CC Workflow Studio is distributed via the VS Code Marketplace and the OpenVSX Registry.

VS Code Marketplace

Install breaking-brake.cc-wf-studio from the Extensions view, or run:

bash
code --install-extension breaking-brake.cc-wf-studio

OpenVSX (VSCodium, Cursor, Windsurf, etc.)

Available as breaking-brake/cc-wf-studio on OpenVSX.

Requirements

  • VS Code 1.80.0 or later (or any compatible editor)
  • Node.js 18+ on your machine (only needed when running workflows that shell out to AI CLIs)
  • Optional: Claude Code, GitHub Copilot Chat/CLI, Codex CLI, Cursor, Roo Code, Gemini CLI, or Antigravity — install whichever target agents you plan to export to

After installation

Open the editor with CC Workflow Studio: Open Editor from the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) or click the icon in the top-right corner of the editor.

File: docs/docs/integrations.md

Integrations

CC Workflow Studio exports the same workflow to eight different AI coding tools. Pick whichever one your team is using — the canvas stays the same.

Tool Output directory Activation
Claude Code .claude/agents/, .claude/commands/ Enabled by default
GitHub Copilot Chat .github/prompts/ Toolbar More menu
GitHub Copilot CLI .github/skills/ Toolbar More menu
Codex CLI .codex/skills/ Toolbar More menu
Cursor .cursor/agents/, .cursor/skills/ Toolbar More menu
Roo Code .roo/skills/ Toolbar More menu
Gemini CLI .gemini/skills/ Toolbar More menu
Antigravity .agent/skills/ Toolbar More menu

Claude Code

Claude Code is the primary export target. Workflows are written to two directories under your project root:

  • .claude/agents/ — full agent definitions
  • .claude/commands/ — slash commands you can invoke as /<workflow-name> inside Claude Code

No activation step is needed; the Claude Code exporter is enabled by default.

GitHub Copilot

CC Workflow Studio targets both Copilot surfaces:

  • Copilot Chat — exports prompts to .github/prompts/ for use inside the chat panel
  • Copilot CLI — exports skills to .github/skills/ for use from the gh copilot command line

Activate the Copilot exporters from the toolbar's More menu. Both targets share the same workflow source.

Codex CLI

OpenAI Codex CLI skills are exported to .codex/skills/. If your workflow contains a Codex Agent node, that step will be executed by Codex regardless of which target you exported to.

Cursor

Cursor gets two output directories, mirroring the Claude Code split:

  • .cursor/agents/ — full agent definitions
  • .cursor/skills/ — reusable skills

Roo Code, Gemini CLI, Antigravity

These three targets share the same skill-export shape:

  • Roo Code — Roo Code writes to .roo/skills/
  • Gemini CLI — Gemini CLI writes to .gemini/skills/
  • Antigravity — Antigravity writes to .agent/skills/

File: docs/docs/nodes.md

Nodes

The Node Palette groups nodes into four sections that mirror the sidebar in the editor. Every workflow also begins with a Start node, added automatically when you create a new workflow.

Basic Nodes

Prompt

Template with variables. The most common building block — a free-text instruction, optionally parameterized, that gets sent to the AI agent.

Sub-Agent

Execute a specialized task. Delegate a single step to a separate agent context, isolating expensive context (large files, long histories) from the parent flow.

Skill

Execute a Claude Code Skill. Reference an Agent Skill (SKILL.md) from ~/.claude/skills/ or the project-level .claude/skills/. Compose workflows from a curated skill library instead of copy-pasting prompts.

MCP Tool

Execute an MCP tool. Call a tool exposed by any registered MCP server, with three configuration modes:

  1. Manual parameter config — fill in tool parameters by hand
  2. AI parameter config — let the agent decide parameter values at runtime
  3. AI tool selection — let the agent pick which tool to call from a curated list

The node integrates with VS Code's MCP configuration (user, project, and enterprise scopes), so any server you've registered in Claude Code is available here.

Special Nodes

Codex Agent (Beta)

Execute OpenAI Codex CLI. Targets Codex specifically for the step, instead of the host agent. Requires enabling Codex Beta in settings.

Layout

Group

A visual container that bundles related nodes together. Groups don't change runtime behavior — they exist to keep large canvases readable.

Control Flow

If/Else

Binary conditional branch (True/False). Use this for simple yes/no decisions.

Switch

Multi-way conditional branch (2–N cases). Define any number of labeled cases plus a default branch. Use this when the agent needs to choose between several distinct paths.

Ask User Question

Pause the workflow and prompt the user for input before continuing — a confirmation, a target file path, or a free-text response to branch on.

End

Workflow termination point. A workflow can have multiple End nodes — one per branch — to represent different outcomes.

File: docs/docs/quick-start.md

Quick Start

1. Install

Install CC Workflow Studio from the VS Code Marketplace or OpenVSX. See Installation for details.

2. Open the editor

  • Command Palette (Cmd+Shift+P / Ctrl+Shift+P) → CC Workflow Studio: Open Editor
  • Or click the CC Workflow Studio icon in the top-right corner of the editor

3. First-launch tour

The first time you open the editor, a sample GitHub issue planning workflow is loaded onto the canvas and a 7-step tour starts automatically:

  1. Welcome — short intro to what you're looking at
  2. Canvas — drag nodes to move, drag handles (⚪) to connect
  3. Property Panel — click a node to edit its name, prompt, model, etc.
  4. Node Palette — add Prompt, Sub-Agent, Skill, MCP Tool, If/Else, Switch, and more
  5. Toolbar Actions — Save, Load, Convert, and Run workflows
  6. Edit with AI — generate or refine workflows conversationally
  7. Finish — you're ready to build

You can re-run the tour anytime from the More menu → Help.

4. Build your own workflow

  1. Click New (or clear the sample) to start with a blank canvas
  2. Drag a Start node, then a Prompt node, then an End node from the Node Palette
  3. Connect them by dragging between the ⚪ handles
  4. Click a node to configure it in the Property Panel
  5. Click Save — the workflow is written to .vscode/workflows/<name>.json

5. Export and run

Two toolbar buttons turn your workflow into something your AI tool can use:

  • Export — generates a Markdown file (slash command, agent skill, or prompt) for the selected AI tool
  • Run — invokes the AI tool with the exported workflow attached

Each integration writes to a tool-specific directory. See Integrations for the full list.

Next steps

  • Nodes — full list of node types you can drop on the canvas
  • Edit with AI — let an AI agent modify the canvas through the built-in MCP server
  • Workflow JSON Schema — shape of the workflow data

File: docs/docs/what-is.md

What is CC Workflow Studio

CC Workflow Studio is a VS Code extension that lets you design AI agent workflows on a visual canvas and export them as Markdown files that AI coding tools (Claude Code, GitHub Copilot, Cursor, Codex CLI, and others) understand natively.

You think visually. AI thinks in .md. CC Workflow Studio speaks both.

Why visual?

Prompt-only workflow authoring becomes hard to maintain as soon as you have more than a handful of steps, branches, or sub-agents. A canvas gives you:

  • A clear overview of the entire flow
  • Explicit branching, loops, and sub-agent boundaries
  • Reusable nodes (Skills, MCP tools) you can drop in instead of re-prompting

What you get

  • Visual editor built on React Flow
  • 12 node types covering control flow, sub-agents, skills, MCP tools, and user prompts
  • 8 export targets for the major AI coding tools
  • Built-in MCP server so AI agents can edit the canvas for you

Ready to try it? Head to Quick Start.

File: docs/docs/workflow-schema.md

Workflow JSON Schema

Workflows are stored as JSON files under .vscode/workflows/<name>.json. The schema (resources/workflow-schema.json in the cc-wf-studio repository) is the source of truth for both the editor and external MCP clients.

Top-level shape

json
{
  "schemaVersion": "1.0.0",
  "name": "my-workflow",
  "nodes": [ ... ],
  "edges": [ ... ]
}
  • schemaVersion — pinned to the schema version the workflow was written against
  • name — display name; also used as the exported command/skill filename
  • nodes — array of node objects (see below)
  • edges — array of connections between node ports

Supported node types

Type Purpose
start Entry point — exactly one per workflow
end Exit point — at least one required
prompt Instruction or message step
subAgent Delegate a step to a sub-agent
subAgentFlow Embed an entire workflow as a sub-agent
codex Run a step with OpenAI Codex CLI
skill Reference a SKILL.md Agent Skill
mcp Call a tool on a registered MCP server
askUserQuestion Pause and ask the user for input
ifElse Binary branching
switch Multi-way branching
group Visual grouping of related nodes

Each node has its own required / optional fields, length limits, and allowed enum values. See the schema file for the authoritative definitions.

Node shape

json
{
  "id": "node-1",
  "type": "prompt",
  "position": { "x": 120, "y": 80 },
  "data": {
    "label": "Summarize the input",
    "prompt": "Summarize the following text in 3 bullet points…"
  }
}
  • id — unique within the workflow
  • type — one of the types above
  • position — canvas coordinates
  • data — type-specific fields (enforced by the schema)

Limits

  • Max nodes per workflow: 100 by default, configurable via the cc-wf-studio.workflow.maxNodes VS Code setting
  • Field lengths: most free-text fields are capped (e.g., prompt at 10,000 characters, description at 200)

Two representations

The schema ships in two formats:

  • resources/workflow-schema.json — the source of truth, edited by humans
  • resources/workflow-schema.toon — a token-efficient format generated from the JSON schema at build time, used when sending the schema to AI agents. Never edit this file by hand

File: docs/index.md

layout: home

hero:
name: CC Workflow Studio
text: Design AI workflows visually.
tagline: A VS Code extension that lets you compose multi-agent workflows on a canvas and export them as native commands for Claude Code, GitHub Copilot, Cursor, and more.
image:
src: /hero.png
alt: CC Workflow Studio canvas screenshot
actions:
- theme: brand
text: Get Started
link: /docs/quick-start
- theme: alt
text: Install on Marketplace
link: https://marketplace.visualstudio.com/items?itemName=breaking-brake.cc-wf-studio
- theme: alt
text: GitHub
link: https://github.com/breaking-brake/cc-wf-studio

features:

  • icon: 🎨
    title: Visual Workflow Editor
    details: Drag-and-drop canvas powered by React Flow. Compose Sub-Agents, Skills, MCP tools, and conditional branches without writing prompts by hand.
    link: /docs/quick-start
  • icon: 🔁
    title: Multi-Agent Export
    details: One workflow, eight targets — Claude Code, Copilot Chat & CLI, Codex CLI, Cursor, Roo Code, Gemini CLI, and Antigravity.
    link: /docs/integrations
  • icon: ✨
    title: Edit with AI via MCP
    details: A built-in MCP server lets external AI agents read and modify the canvas directly. Iterate on workflows through natural language.
    link: /docs/edit-with-ai

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →