cc-wf-studio Documentation

1. Project Overview & Quickstart (breaking-brake/cc-wf-studio) Copy Chapter

File: README.md Copy Chapter

CC Workflow Studio

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

Design workflows on a canvas. Export as Markdown your AI agent already understands. No more prompt-guessing.

Supported Agents Copy Chapter

Note: Agents other than Claude Code require activation from Toolbar's More menu.

Use it without VSCode, too Copy Chapter

The VSCode extension is the most ergonomic editor, but it isn't the only entry point. The same workflow.json drives a CLI and an MCP server — pick whichever interface fits the situation.

flowchart LR
    Wf(["workflow.json"])

    subgraph IDE["🪟 VSCode Extension"]
        Canvas["React Flow canvas+ editor + Slack share"]
    end

    subgraph Mcp["🔌 MCP Server"]
        AIClient["Claude Code,MCP Inspector, ..."]
        McpServer["@cc-wf-studio/mcp(stdio: `ccwf-mcp`)"]
        AIClient --> McpServer
    end

    subgraph Cli["💻 CLI"]
        CliBin["@cc-wf-studio/cli(`ccwf render | validate | export | run | preview | canvas | mcp`)"]
    end

    Wf <-->|edit| Canvas
    Wf <-->|read / write| McpServer
    Wf <-->|read / write| CliBin

    Canvas -.->|writes skills + agents| Output["Agent skills on disk(.claude/, .codex/, .cursor/, ...)"]
    McpServer -.-> Output
    CliBin -.-> Output

There is no "VSCode-only" path: a workflow you draw in the canvas is the same file ccwf preview will render in a browser, and the same file an external Claude Code can edit through MCP.

Key Features Copy Chapter

🔀 Visual Workflow Editor - Intuitive drag-and-drop canvas for designing AI agent orchestrations without code

🤖 Agentic Engineering - Design multi-agent workflows with Sub-Agent orchestration, Agent Skills, and MCP tool integration — the building blocks of agentic engineering

✨ Edit with AI - Iteratively improve workflows through conversational AI - ask for changes, add features, or refine logic with natural language feedback

⚡ One-Click Export & Run - Export workflows to ready-to-use formats and run directly from the editor

How to Use Copy Chapter

Launch the Extension Copy Section

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

Create a Workflow Copy Section

• Add nodes from the palette and configure their settings, or use Edit with AI.

Save & Load Copy Section

• Click Save button in the toolbar to store your workflow as .vscode/workflows/*.json
• Click Load button in the toolbar to open a saved .json workflow

Export & Run Copy Section

• Click Export button in the toolbar to create a .md slash command or agent skill (use /workflow-name in AI coding agents)
• Click Run button in the toolbar to run your workflow directly in AI coding agents

Edit with AI Copy Section

• Click Edit with AI button in the toolbar to generate or refine workflows with natural language
• Native with MCP Server: Click an AI agent button in the Edit with AI panel to launch native AI editing. The MCP server starts automatically behind the scenes.

sequenceDiagram
    actor User
    box VS Code (CC Workflow Studio)
        participant UI as Editor UI
        participant MCP as MCP Server
    end
    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_workflow
        MCP-->>Agent: workflow JSON
        Agent->>MCP: apply_workflow
        MCP->>UI: Update canvas
    end

Usage Examples Copy Chapter

Coming soon - Sample workflows and tutorials are under development.

License Copy Chapter

The VSCode extension (cc-wf-studio) is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later).

See the LICENSE file for the full license text.

The reusable libraries published to npm — @cc-wf-studio/core, @cc-wf-studio/mcp, and @cc-wf-studio/cli — are released under the more permissive MIT license. Each package ships its own LICENSE file, which takes precedence for that package.

Copyright (c) 2025 breaking-brake

Star History Copy Chapter

Acknowledgments Copy Chapter

Built with React Flow • Powered by Claude Code • Inspired by Dify

Made with CC Workflow Studio

File: docs/release-flow.md Copy Chapter

Release Flow

This repository uses Changesets for versioning across the pnpm workspace. A release is cut manually (you open the Release PR when ready) and published automatically when that PR merges into main. There is no production branch in the flow anymore and no manual publish dispatch.

TL;DR for contributors Copy Chapter

1. Open a feature/fix PR against main.
2. If your change affects a published package, run pnpm changeset locally and commit the generated .changeset/<name>.md. (Docs/chore-only PRs: pnpm changeset add --empty.)
3. Check the changeset-bot comment on your PR — 🦋 means a changeset was detected, ⚠️ means none was found. Add one if the PR should release something; add an empty one if it intentionally shouldn't.
4. Merge your PR. Nothing is released yet — changesets just accumulate on main.
5. When you decide to release, a maintainer runs the "Release — Create Release PR" workflow from the Actions UI. It opens a chore(release): version packages PR previewing the version bumps + CHANGELOG diff.
6. Review and merge that Release PR into main. The merge triggers "Release — Publish" automatically: it publishes the npm packages, creates the tags, and uploads the VSIX for cc-wf-studio.
7. The Repository Owner uploads the VSIX from the GitHub Release to the VS Marketplace / Open VSX (manual — see below).

[!IMPORTANT]
Releasing is a human-only action. AI agents must NOT self-trigger any release step — do not run the "Release — Create Release PR" workflow, do not merge the Release PR into main, and do not dispatch publish workflows. Merging the Release PR is an irreversible publish (npm cannot be re-published). Agents may prepare changes and explain this procedure, but a human performs the actual release actions.

Design: confirm = release Copy Chapter

The Release PR is created manually (deliberate "cut a release" action) and merging it auto-publishes. Because the version-bump commit and the publish happen on the same branch back-to-back, a version can never sit "confirmed but unpublished" — so npm version numbers never skip. To avoid frequent/jumpy versions, simply let changesets accumulate on main and cut a release only when ready; multiple pending changesets collapse into a single bump (highest level wins).

Branch model Copy Chapter

• main — the one and only release branch. Feature work branches off main and merges back via PR. The Release PR also lands here, and publishing happens from main.
• production — frozen / legacy. It is no longer part of the release flow; do not promote to it. It is kept only so historical commits/tags remain easy to reference. (Git tags are independent of branches and are unaffected regardless.)

Two workflows Copy Chapter

The release.yml check job is what makes "publish on every push to main" safe: ordinary feature merges still carry .changeset/*.md, so should_publish is false and the publish job is skipped. Only the Release PR merge (changesets consumed, versions bumped) publishes. pnpm changeset publish is also idempotent — it only publishes versions ahead of the registry — so any stray no-op push is harmless.

What each package looks like at release Copy Chapter

cc-wf-studio is "private": true, so Changesets versions and tags it but does not push it to npm. The workflow detects the tag, builds the VSIX, and attaches it to the GitHub Release.

cc-wf-studio-webview is in the Changesets ignore list — it is bundled into @cc-wf-studio/cli and the extension at build time, never published on its own.

End-to-end flow Copy Chapter

sequenceDiagram
    actor Dev as Developer
    participant Main as main
    actor Maint as Maintainer
    participant CRP as release-version-pr.yml (manual)
    participant RPR as "Version Packages" PR
    participant CI as release.yml (push:main)
    participant NPM as npm registry
    participant GH as GitHub Release

    Dev->>Main: feature PR + .changeset/xxx.md (merge, accumulates)
    Maint->>CRP: Actions UI "Run workflow" (cut a release)
    CRP->>RPR: open / update Release PR (bump + CHANGELOG preview)
    Maint->>RPR: review + merge into main
    RPR->>Main: version bump commit lands (changesets consumed)
    Main->>CI: push triggers release.yml
    Note over CI: check job: no pending changesets → publish
    CI->>NPM: pnpm changeset publish (OIDC + provenance)
    CI->>GH: tags + Releases per package
    CI->>GH: cc-wf-studio tag + Release, VSIX uploaded
    Maint->>Maint: upload VSIX to Marketplace / Open VSX (manual)

npm authentication: OIDC Trusted Publishing Copy Chapter

npm publishes use OIDC Trusted Publishing — there is no NPM_TOKEN secret. Each of @cc-wf-studio/{core,mcp,cli} has a Trusted Publisher configured on npmjs.com pointing at breaking-brake/cc-wf-studio → release.yml. The trusted publisher is bound to the workflow file name, not its trigger, so switching release.yml from dispatch to push did not require any npm-side reconfiguration. The publish workflow sets NPM_CONFIG_PROVENANCE: 'true', so each release carries a provenance attestation visible on npmjs.com.

VS Marketplace / Open VSX (manual) Copy Chapter

The workflow does not push the extension to the Marketplace. It only builds the .vsix and attaches it to the [email protected] GitHub Release. The store publish is manual:

1. "Release — Publish" uploads packages/vscode/*.vsix to the GitHub Release.
2. The Repository Owner downloads that .vsix.
3. The Repository Owner uploads it to the VS Marketplace (and Open VSX) via the publisher portal.

So the GitHub Release .vsix is the source artifact for the store listing — there is no vsce publish / ovsx publish in CI.

Independent versions + internal dependency propagation Copy Chapter

Each workspace package is versioned independently — there is no fixed or linked group in .changeset/config.json.

flowchart LR
    Core["@cc-wf-studio/core0.x.y"]
    CLI["@cc-wf-studio/cli0.x.y"]
    MCP["@cc-wf-studio/mcp0.x.y"]
    VSCode["cc-wf-studio3.x.y (continued)"]

    Core -->|workspace dep| CLI
    Core -->|workspace dep| MCP
    Core -->|workspace dep| VSCode

• cc-wf-studio keeps its existing 3.34.x stream so the Marketplace listing stays continuous.
• New packages start at pre-1.0 ([email protected], [email protected], [email protected]).
• updateInternalDependencies: "patch" is set, so bumping @cc-wf-studio/core automatically bumps cli / mcp (patch) and updates their dependency ranges — no separate changeset needed for the dependents.
• workspace:* dependencies are replaced with the actual published versions when changeset publish runs.

Required secrets Copy Chapter

No NPM_TOKEN — npm publishing is via OIDC Trusted Publishing.

Authoring a changeset Copy Chapter

pnpm changeset

The interactive prompt asks: which packages changed, the bump level (patch / minor / major), and a summary used for the CHANGELOG entry. Commit the generated file alongside your code. You never hand-edit CHANGELOG.md — Changesets generates it.

Changeset bot Copy Section

The changeset-bot GitHub App is installed on this repository. It comments on every PR to show whether a changeset is present:

• 🦋 Changeset detected — the PR adds a .changeset/*.md file (a real bump or an empty one).
• ⚠️ No Changeset found — the PR adds none. This is a reminder, not a blocker. If the PR genuinely needs no release, add an empty changeset (pnpm changeset add --empty) to make the intent explicit and clear the warning.

There is no hard CI gate that fails the build on a missing changeset; the bot comment plus the human review at the Release PR are the safety net.

What doesn't trigger a release Copy Chapter

• Pushes to branches other than main.
• An ordinary feature merge to main — it carries pending changesets, so release.yml's check job skips publishing.
• Merging the Release PR does publish (this is the deliberate release trigger).
• A push to main with no version bump (e.g. a docs PR with no changeset) — changeset publish finds nothing ahead of the registry and no-ops.

Prior release flows (for reference) Copy Chapter

• Original: semantic-release on push to production (commit-message driven), with auto-sync production → main.
• Then: Changesets with a manual publish dispatch from a production branch (Version PR auto-opened on push to main; guard-production.yml blocked premature promotes).
• Current: Changesets with a manually-created Release PR whose merge into main auto-publishes (OIDC). production is frozen; guard-production.yml was removed. This couples confirm = release so version numbers don't skip.

File: packages/vscode/docs/ai-coding-tools-config-reference.md Copy Chapter

AI Coding Tools Configuration Reference

A summary of configuration file paths for each AI coding tool.
Created by referencing official documentation for each tool.

Summary Table Copy Chapter

Claude Code Copy Chapter

Reference:

• Claude Code Settings
• Extend Claude with Skills

Memory (CLAUDE.md) Copy Section

Settings Copy Section

Managed settings locations:

• macOS: /Library/Application Support/ClaudeCode/
• Linux/WSL: /etc/claude-code/
• Windows: C:\Program Files\ClaudeCode\

Skills Copy Section

Note: Skills in subdirectories (e.g., packages/frontend/.claude/skills/) are auto-discovered

Frontmatter Schema:

---
name: skill-name                    # Optional (uses directory name if omitted)
argument-hint: "[issue-number]"     # Optional
disable-model-invocation: false     # Optional, prevent auto-loading
user-invocable: true                # Optional, hide from / menu if false
allowed-tools:                      # Optional
  - Bash
  - Read
  - Write
model: claude-sonnet-4-5            # Optional
context: fork                       # Optional, run in subagent
agent: Explore                      # Optional, subagent type
hooks: {}                           # Optional, skill-scoped hooks
---

Commands (Legacy) Copy Section

Note: Commands are merged into Skills. Both .claude/commands/review.md and .claude/skills/review/SKILL.md create /review. Skills are recommended.

Frontmatter Schema:

---
allowed-tools:                      # Optional
  - Bash
argument-hint: "[filename]"         # Optional
model: claude-sonnet-4-5            # Optional
disable-model-invocation: false     # Optional
---

Agents (Subagents) Copy Section

MCP Copy Section

JSON Schema:

{
  "mcpServers": {
    "server-name": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "package-name"],
      "env": {}
    }
  }
}

Ignore Copy Section

Gemini CLI Copy Chapter

Google Gemini CLI is a terminal-based AI coding agent.

Reference:

• Gemini CLI Installation
• Gemini CLI Configuration
• GEMINI.md Files
• Agent Skills
• Custom Commands
• MCP Servers
• Extensions

Installation Copy Section

Prerequisites: Node.js 20.0.0+

Rules (GEMINI.md) Copy Section

Features:

• @file.md syntax to import other Markdown files
• /memory show to display current combined context
• /memory refresh to reload all context files
• /memory add <text> to append text to ~/.gemini/GEMINI.md
• GEMINI_SYSTEM_MD environment variable to override system prompt

Custom context file names (settings.json):

{
  "context": {
    "fileName": ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]
  }
}

Skills Copy Section

Directory structure:

.gemini/skills/my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable scripts
├── references/       # Optional: static documentation
└── assets/           # Optional: templates/resources

Frontmatter Schema:

---
name: skill-name           # Required
---

Lifecycle:

1. Discovery: CLI scans 3 layers; only name and description are injected into system prompt
2. Activation: Model calls activate_skill tool when task matches (user confirmation required)
3. Injection: After approval, SKILL.md body + folder structure are added to conversation

CLI commands: gemini skills list, gemini skills install, gemini skills link

settings.json:

{
  "skills": {
    "enabled": true,
    "disabled": ["skill-name"]
  }
}

Commands (Custom Commands) Copy Section

Note: Project commands override same-named user commands. Filename becomes command name (e.g., test.toml → /test, git/commit.toml → /git:commit).

TOML Schema:

description = "Generate a commit message"    # Optional
prompt = """
Review the following staged changes:

!{git diff --staged}

{{args}}
"""

Template syntax:

• {{args}} — User input placeholder
• !{command} — Shell command output injection
• @{file.md} — File content injection

MCP Copy Section

MCP servers are configured in settings.json under mcpServers key.

JSON Schema:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "package-name"],
      "env": {
        "API_KEY": "$ENV_VAR"
      },
      "cwd": "/path/to/dir",
      "timeout": 600000,
      "trust": false,
      "includeTools": ["tool1"],
      "excludeTools": ["tool2"]
    }
  }
}

Transport types: httpUrl > url > command (priority order, at least one required)

Global MCP settings:

{
  "mcp": {
    "allowed": ["serverName"],
    "excluded": ["serverName"]
  }
}

Configuration Copy Section

System settings locations:

• Linux: /etc/gemini-cli/settings.json
• macOS: /Library/Application Support/GeminiCli/settings.json

Precedence order (high → low):

1. CLI arguments (--model, --sandbox, etc.)
2. Environment variables (GEMINI_API_KEY, GEMINI_MODEL, etc.)
3. System settings
4. Project settings (.gemini/settings.json)
5. User settings (~/.gemini/settings.json)
6. System defaults
7. Hard-coded defaults

Note: GEMINI_CLI_HOME environment variable can change the ~/.gemini path

Key environment variables:

Ignore Copy Section

Note: Uses .gitignore syntax. Session restart required after changes.

settings.json related:

{
  "context": {
    "fileFiltering": {
      "respectGitIgnore": true,
      "respectGeminiIgnore": true
    }
  }
}

Extensions Copy Section

Extension directory structure:

.gemini/extensions/my-extension/
├── gemini-extension.json   # Required: manifest
├── GEMINI.md               # Optional: context
├── commands/*.toml          # Optional: custom commands
├── skills/{name}/SKILL.md   # Optional: skills
└── hooks/hooks.json         # Optional: hook definitions

CLI commands: gemini extensions install , gemini extensions list, gemini extensions enable/disable

Antigravity (Google) Copy Chapter

Antigravity is a Google-made VSCode fork with a built-in AI agent called Cascade.

Note: This section is based on reverse engineering of Antigravity v1.107.0 (app bundle analysis). No official public documentation is available.

• Extension ID (built-in): google.antigravity
• Internal codename: Jetski
• App location: /Applications/Antigravity.app
• Config directory: ~/Library/Application Support/Antigravity/

VSCode Commands (AI Agent Interaction) Copy Section

These commands can be used via vscode.commands.executeCommand() to interact with Antigravity's Cascade AI.

Chat / Agent Launch

Standard VSCode Chat API (also supported)

Agent Step Control

Workflow / Rules

Other Notable Commands

Built-in Extensions Copy Section

Rules Copy Section

Rules files use the header # antigravity rules.

Note: antigravity.createRule command is available for rule creation. antigravity.openGlobalRules opens global rules.

Skills (Claude Skills互換) Copy Section

Antigravityは .agent/skills/ ディレクトリ からスキルを読み込む（chat.useClaudeSkills 設定で有効化）。Claude Code の SKILL.md と同一フォーマット。

検出ロジック:

1. .agent/skills/ ディレクトリを探索
2. 各サブディレクトリ内の SKILL.md を検出
3. Frontmatter の name と description をシステムプロンプトに注入
4. ユーザーのタスクがスキルのドメインに一致すると、スキル内容が会話に追加される

Frontmatter Schema:

---
name: skill-name           # Required
---

Note: chat.useClaudeSkills 設定（experimental）で切り替え可能。Claude Code の SKILL.md と同一フォーマット。

MCP Copy Section

Antigravity uses a global MCP configuration at ~/.gemini/antigravity/mcp_config.json.

JSON Schema:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "package-name"],
      "env": {}
    }
  }
}

Note: Uses mcpServers key (same as Claude Code), NOT servers.

Cascade Configuration Copy Section

Cascade has several configuration keys found in the workbench:

CLI Copy Section

Integration Strategy for cc-wf-studio Copy Section

Execution pattern: Closest to Copilot Chat (VSCode command-based).

// Recommended launch pattern
await vscode.commands.executeCommand('antigravity.sendPromptToAgentPanel', prompt);

// Fallback: standard VSCode Chat API
await vscode.commands.executeCommand('workbench.action.chat.open', {
  mode: 'agent',
  query: prompt,
});

MCP config: Shares .vscode/mcp.json with Copilot Chat (same servers key).

Skill file location: .claude/skills/{skill-name}/SKILL.md（Claude Codeと完全互換）。chat.useClaudeSkills 設定で有効化。

VSCode Copilot Chat Copy Chapter

GitHub Copilot Chat functionality within VSCode.

Reference:

• Use custom instructions in VS Code
• Use Agent Skills in VS Code
• Use prompt files in VS Code
• Use MCP servers in VS Code

Rules (Instructions) Copy Section

Frontmatter Schema (modular instructions):

---
applyTo: "**/*.ts,**/*.tsx"    # Optional, comma-separated globs
---

Related Settings:

Skills Copy Section

Frontmatter Schema:

---
name: skill-name        # Required, max 64 characters
---

Related Settings:

Prompts (Commands) Copy Section

Frontmatter Schema:

---
name: prompt-name           # Optional, identifier after /
agent: agent                # Optional: ask | edit | agent | custom-agent-name
model: gpt-4o               # Optional, language model
tools:                      # Optional, available tools
  - Read
  - Write
  - "<mcp-server>/*"        # MCP server tools
argument-hint: "Enter value"  # Optional
---

Usage:

• Type /prompt-name in chat input
• Command Palette: "Chat: Run Prompt"

Related Settings:

MCP Copy Section

JSON Schema:

{
  "inputs": [
    {
      "id": "api-key",
      "type": "promptString",
      "description": "API Key",
      "password": true
    }
  ],
  "servers": {
    "server-name": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "package-name"],
      "env": {
        "API_KEY": "${input:api-key}"
      }
    }
  }
}

Note: Claude Code uses mcpServers key, VSCode Copilot uses servers key

Related Settings:

Copilot CLI Copy Chapter

GitHub Copilot CLI (npm install @github/copilot) is a terminal-based AI coding agent.

Reference:

• Installing GitHub Copilot CLI
• Using GitHub Copilot CLI
• GitHub Copilot CLI Repository

Installation Copy Section

Rules (Instructions) Copy Section

Skills Copy Section

Note: .claude/skills/ is also read for backward compatibility

Frontmatter Schema:

---
name: skill-name        # Required: lowercase, hyphens for spaces
---

Agents (Custom Agents) Copy Section

Priority: Project > Global

MCP Copy Section

Note: Copilot CLI does NOT support project-scope MCP configuration. Only user-scope (~/.copilot/mcp-config.json) is supported.

JSON Schema:

{
  "mcpServers": {
    "server-name": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "package-name"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

Note: Since v0.0.340, environment variables must be explicitly specified using ${VAR} format

Configuration Copy Section

Note: XDG_CONFIG_HOME environment variable can change the ~/.copilot path

Codex CLI (OpenAI) Copy Chapter

OpenAI Codex CLI is a terminal-based AI coding agent.

Reference:

• OpenAI Codex CLI
• Configuration Reference
• Custom instructions with AGENTS.md
• Agent Skills

Rules (AGENTS.md) Copy Section

Precedence order: Global → Project root → ... → Current directory (closer files override earlier)

Note: Custom fallback filenames can be configured via project_doc_fallback_filenames in config.toml

Skills Copy Section

Frontmatter Schema:

---
name: skill-name           # Required
metadata:
  short-description: Brief description  # Optional, user-facing
---

Configuration Copy Section

Note: CODEX_HOME environment variable can change the ~/.codex path

Custom instructions can be added via:

• developer_instructions in config.toml (inline)
• model_instructions_file in config.toml (file path)

MCP Copy Section

MCP servers are configured in ~/.codex/config.toml under mcp_servers..*

TOML Schema (stdio):

[mcp_servers.server-name]
enabled = true
command = "npx"
args = ["-y", "package-name"]
cwd = "/path/to/dir"  # Optional
startup_timeout_sec = 10  # Optional
tool_timeout_sec = 60  # Optional

[mcp_servers.server-name.env]
API_KEY = "value"

TOML Schema (HTTP):

[mcp_servers.server-name]
enabled = true
url = "https://example.com/mcp"
bearer_token_env_var = "MCP_TOKEN"  # Optional

[mcp_servers.server-name.http_headers]
X-Custom-Header = "value"

Zoo Code (formerly Roo Code) Copy Chapter

Zoo Code is the maintained community fork of Roo Code (which itself forked from Roo Cline), a VSCode extension for AI-assisted coding with customizable modes. The original Roo Code extension and its Router service were sunset in 2026; Zoo Code keeps the same .roo/ configuration layout. The directory layouts below apply to both.

Reference:

• Zoo Code Documentation
• Roo → Zoo migration guide
• Legacy Roo Code docs: Custom Instructions, Skills, Slash Commands, Custom Modes, MCP

Rules (Instructions) Copy Section

Directory-based (recommended):

Fallback (single file, used only when directory-based rules don't exist):

AGENTS.md support:

• AGENTS.md at workspace root is read by default
• Disable via: "roo-cline.useAgentRules": false

Note: Rule files in directories are read recursively, sorted alphabetically by base name. Supported formats: .md, .txt, and other plain text files.

Priority (low → high):

1. Global rules (~/.roo/rules/)
2. Workspace rules (.roo/rules/) — overrides global
3. Legacy files (.roorules, .clinerules) — only when directory-based rules don't exist

Skills Copy Section

Frontmatter Schema:

---
name: skill-name           # Required, 1-64 chars, lowercase + hyphens, must match directory name
---

Override priority (high → low):

1. Project mode-specific (.roo/skills-{modeSlug}/)
2. Project general (.roo/skills/)
3. Global mode-specific (~/.roo/skills-{modeSlug}/)
4. Global general (~/.roo/skills/)

Note: Skills are fully disabled when .roo/system-prompt-{mode-slug} exists.

Commands (Slash Commands) Copy Section

Frontmatter Schema:

---
argument-hint:     # Optional
mode: mode-slug                      # Optional, mode to use when executing
---

Note: Filename becomes command name (e.g., review.md → /review). Project commands override same-named global commands.

Modes (Custom Agents) Copy Section

globalStorage paths:

• macOS: ~/Library/Application Support/Code/User/globalStorage/zoocodeorganization.zoo-code/
• Linux: ~/.config/Code/User/globalStorage/zoocodeorganization.zoo-code/
• Windows: %APPDATA%\Code\User\globalStorage\zoocodeorganization.zoo-code\

Schema:

customModes:
  - slug: my-mode              # Required: /^[a-zA-Z0-9-]+$/
    name: My Custom Mode       # Required: display name
    roleDefinition: |          # Required: system prompt prefix
      You are an expert in...
    groups:                    # Required: tool access control
      - read
      - - edit
        - fileRegex: \.(md|mdx)$
      - browser
      - command
      - mcp
    whenToUse: |                 # Optional: orchestration guidance
      Use this mode when...
    customInstructions: |        # Optional: appended to system prompt
      Additional guidelines...

Built-in modes: code, debug, ask, architect, orchestrator

MCP Copy Section

JSON Schema (STDIO):

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "cwd": "/working/directory",
      "env": {
        "API_KEY": "your-key"
      },
      "alwaysAllow": ["tool1", "tool2"],
      "disabled": false
    }
  }
}

JSON Schema (Streamable HTTP):

{
  "mcpServers": {
    "server-name": {
      "type": "streamable-http",
      "url": "https://example.com/mcp",
      "headers": {},
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

Note: Project-level overrides global when same server name is defined in both.

Ignore Copy Section

Note: Uses .gitignore syntax. Affects read_file, write_to_file, apply_diff, list_code_definition_names tools.

System Prompt Override Copy Section

Warning: This bypasses all standard sections (tool descriptions, rules, skills). Use with caution.

Directory Structure Comparison Copy Chapter

Project Level Copy Section

/* Detailed source-code truncated for AI context efficiency. */

User Level (Global) Copy Section

/* Detailed source-code truncated for AI context efficiency. */

VSCode Copilot Chat vs Copilot CLI Comparison Copy Chapter

References Copy Chapter

• Antigravity: No official public documentation. Information reverse-engineered from app bundle v1.107.0.
• Claude Code Documentation
• Claude Code Settings
• Claude Code Skills
• Gemini CLI GitHub Repository
• Gemini CLI Installation
• Gemini CLI Configuration
• Gemini CLI GEMINI.md
• Gemini CLI Skills
• Gemini CLI Custom Commands
• Gemini CLI MCP Servers
• Gemini CLI .geminiignore
• Gemini CLI Extensions
• Zoo Code Documentation
• Legacy Roo Code docs (layout still applies to Zoo Code):
  • Roo Code Custom Instructions
  • Roo Code Skills
  • Roo Code Slash Commands
  • Roo Code Custom Modes
  • Roo Code MCP
  • Roo Code .rooignore
  • Roo Code System Prompt Override
• Use custom instructions in VS Code
• Use Agent Skills in VS Code
• Use prompt files in VS Code
• Use MCP servers in VS Code
• Installing GitHub Copilot CLI
• Using GitHub Copilot CLI
• GitHub Copilot CLI Repository
• OpenAI Codex CLI
• Codex Configuration Reference
• Codex Agent Skills
• Codex AGENTS.md Guide

File: packages/vscode/docs/release-automation.md Copy Chapter

リリース自動化ガイド

このドキュメントでは、productionブランチへのマージ時に自動的にバージョンアップとGitHubリリースを作成する仕組みについて説明します。

概要 Copy Chapter

このプロジェクトでは semantic-release と Conventional Commits を使用した完全自動リリースシステムを採用しています。

自動化される内容 Copy Section

1. バージョン決定: コミットメッセージから自動的にバージョンタイプ (major/minor/patch) を判定
2. バージョン更新: package.json と src/webview/package.json のバージョンを自動更新
3. CHANGELOG生成: コミット履歴から自動的に CHANGELOG.md を生成
4. GitHubリリース: リリースノート付きのGitHubリリースを自動作成
5. VSIXパッケージ: ビルドされた .vsix ファイルをリリースに添付
6. ブランチ同期: productionブランチでリリース後、自動的にmainブランチへバージョンをマージ

セットアップ Copy Chapter

1. GitHub Settings Copy Section

このワークフローは GITHUB_TOKEN を使用しますが、デフォルトで提供されるため追加設定は不要です。

ただし、リポジトリの設定で以下を確認してください:

1. Settings > Actions > General
2. Workflow permissions セクションで以下を選択:
   • ✅ Read and write permissions
   • ✅ Allow GitHub Actions to create and approve pull requests

2. ブランチ保護ルール (オプション) Copy Section

productionブランチを保護する場合:

1. Settings > Branches > Add branch protection rule
2. Branch name pattern: production
3. 推奨設定:
   • ✅ Require a pull request before merging
   • ✅ Require status checks to pass before merging
   • ⚠️ Do not enable "Include administrators" (semantic-releaseがコミットできなくなります)

使い方 Copy Chapter

Conventional Commits の書き方 Copy Section

コミットメッセージは以下の形式に従ってください:

<type>(<scope>): <subject>



<footer>

Type (必須)

Breaking Changes (major バージョンアップ)

major バージョン (X.0.0) にするには、以下のいずれかを使用:

方法1: Footer に記載

feat: 新しいAPI設計に変更

BREAKING CHANGE: 旧APIは削除されました。新しいAPIを使用してください。

方法2: Type に ! を追加

feat!: 新しいAPI設計に変更

旧APIは削除されました。

Scope (オプション)

変更範囲を示す識別子:

feat(webview): 新しいUIコンポーネントを追加
fix(extension): ワークフロー保存時のバグを修正
docs(readme): インストール手順を更新

実践例 Copy Section

新機能追加 (minor バージョンアップ)

git commit -m "feat: ワークフローのエクスポート機能を追加

ユーザーがワークフローをJSON形式でエクスポートできるようになりました。"

結果: 2.0.3 → 2.1.0

バグ修正 (patch バージョンアップ)

git commit -m "fix: ノード削除時のクラッシュを修正"

結果: 2.0.3 → 2.0.4

Breaking Change (major バージョンアップ)

git commit -m "feat!: 新しいワークフローフォーマットに移行

BREAKING CHANGE: 旧形式のワークフローファイルは手動で移行が必要です。"

結果: 2.0.3 → 3.0.0

リリース対象外 (バージョンアップなし)

git commit -m "docs: READMEのタイポを修正"
git commit -m "test: ユニットテストを追加"
git commit -m "chore: 依存関係を更新"

結果: バージョン変更なし

リリースフロー Copy Section

1. 開発ブランチで作業

   bash Copy

   git checkout -b feature/my-feature
   # 開発作業...
   git commit -m "feat: 新機能を追加"

2. mainブランチにマージ

   bash Copy

   git checkout main
   git merge feature/my-feature
   git push origin main

3. productionブランチにマージ (リリーストリガー)

   bash Copy

   git checkout production
   git merge main
   git push origin production

4. 自動リリースが実行される (productionブランチ)

   • GitHub Actionsが起動
   • コミット履歴を分析
   • バージョンを決定
   • package.json を更新
   • CHANGELOG.md を生成
   • GitHubリリースを作成
   • .vsix ファイルを添付
   • 自動的にmainブランチへバージョンをマージ (chore: sync version from production [skip ci])

トラブルシューティング Copy Chapter

リリースが実行されない Copy Section

原因1: リリース対象のコミットがない

• 最後のリリース以降、feat, fix, perf などのコミットがない
• docs, chore, test などはリリースを生成しません

原因2: GitHub Actionsの権限不足

• Settings > Actions > General で権限を確認

原因3: ブランチ保護ルールが厳しすぎる

• semantic-releaseがコミットできるようにする必要があります

バージョンが期待通りに上がらない Copy Section

原因: コミットメッセージの形式が正しくない

• Conventional Commitsの形式に従っているか確認
• Typo がないか確認 (例: feat を feature と書いていないか)

確認方法:

# コミット履歴を確認
git log --oneline --since="2025-01-01"

# 特定のコミットの詳細を確認
git show <commit-hash>

手動でリリースをやり直したい Copy Section

# ローカルで semantic-release を実行 (dry-run)
npx semantic-release --dry-run

# 実際に実行 (注意: 本番環境に影響します)
GITHUB_TOKEN=<your-token> npx semantic-release

CI/CD パイプライン詳細 Copy Chapter

ワークフローステップ Copy Section

1. Checkout: リポジトリの全履歴を取得 (fetch-depth: 0)
2. Setup Node.js: Node.js 20をセットアップ
3. Install dependencies: ルートと webview の依存関係をインストール
4. Build: 拡張機能をビルド
5. Package: .vsix ファイルを生成
6. Sync version: webview の package.json バージョンを同期
7. Semantic Release: バージョン判定とリリース実行
8. Sync to main (productionブランチのみ): リリース後、mainブランチへ自動マージ

更新されるファイル Copy Section

semantic-releaseは以下のファイルを自動更新してコミットします:

• package.json (バージョン番号)
• src/webview/package.json (バージョン番号)
• src/webview/package-lock.json (バージョン同期)
• CHANGELOG.md (リリースノート)

コミットメッセージ:

chore(release): 2.1.0 [skip ci]

# Release notes
...

[skip ci] により、このコミットで再度CIが起動することを防ぎます。

ブランチ同期の仕組み Copy Section

productionブランチでリリースが成功した後:

1. productionブランチをフェッチ (semantic-releaseが作成したリリースコミットを取得)
2. mainブランチをフェッチ
3. mainブランチにチェックアウト
4. productionブランチの変更をマージ (chore: sync version from production [skip ci])
5. mainブランチにプッシュ

これにより、mainとproductionの両方が同じバージョンになります。
[skip ci] により、このマージコミットでCIが再実行されることを防ぎます。

重要: semantic-releaseがproductionブランチにリリースコミットを作成した後、必ず git fetch origin production を実行してから同期を行います。これにより、ワークフロー開始時にチェックアウトされた古い状態ではなく、最新のリリースコミットが含まれた状態でマージされます。

参考資料 Copy Chapter

• Conventional Commits
• semantic-release
• GitHub Actions

File: packages/vscode/docs/schema-maintenance.md Copy Chapter

Workflow Schema Maintenance Guide

Overview Copy Chapter

This guide explains how to maintain synchronization between TypeScript type definitions and the AI workflow schema documentation.

Key Files Copy Chapter

Source of Truth: TypeScript Type Definitions Copy Section

• File: src/shared/types/workflow-definition.ts
• Contains:
  • NodeType enum - All supported node types
  • Node data interfaces (SubAgentData, AskUserQuestionData, etc.)
  • VALIDATION_RULES - Validation constraints

AI Documentation: Workflow Schema JSON Copy Section

• File: resources/workflow-schema.json
• Purpose: Machine-readable schema for AI to generate workflows
• Contains:
  • Node type definitions with fields and constraints
  • Validation rules (maxNodes, field lengths, patterns)
  • Example workflows
  • Connection rules

When to Update Copy Chapter

Update resources/workflow-schema.json whenever you:

1. Add a new node type to NodeType enum
2. Modify node data interfaces (add/remove/change fields)
3. Change VALIDATION_RULES (maxNodes, maxLength, patterns, etc.)
4. Deprecate node types (e.g., Branch → IfElse/Switch)

Update Procedure Copy Chapter

1. Modify TypeScript Type Definitions Copy Section

Edit src/shared/types/workflow-definition.ts:

// Example: Adding a new node type
export enum NodeType {
  // ... existing types
  NewNodeType = 'newNodeType',
}

// Example: Updating validation rules
export const VALIDATION_RULES = {
  WORKFLOW: {
    MAX_NODES: 50, // Changed from 30
  },
  // ... other rules
};

2. Update Workflow Schema JSON Copy Section

Edit resources/workflow-schema.json:

Adding a New Node Type

{
  "nodeTypes": {
    "newNodeType": {
      "description": "Brief description of what this node does",
      "fields": {
        "fieldName": {
          "type": "string",
          "required": true,
          "maxLength": 100
        }
      },
      "inputPorts": 1,
      "outputPorts": 1
    }
  }
}

Updating Validation Rules

{
  "metadata": {
    "maxNodes": 50  // Match VALIDATION_RULES.WORKFLOW.MAX_NODES
  },
  "nodeTypes": {
    "subAgent": {
      "fields": {
        "prompt": {
          "maxLength": 10000  // Match VALIDATION_RULES.SUB_AGENT.PROMPT_MAX_LENGTH
        }
      }
    }
  }
}

Adding Example Workflows

Update the examples array with relevant examples demonstrating the new features:

{
  "examples": [
    {
      "name": "Example showing new node type",
      "nodes": [...],
      "connections": [...]
    }
  ]
}

3. Verify Synchronization Copy Section

Run the verification script (if available) or manually check:

# Check that all NodeType values are documented
grep -o "NodeType\.[A-Za-z]*" src/shared/types/workflow-definition.ts

# Check nodeTypes in schema
cat resources/workflow-schema.json | python3 -m json.tool | grep -A 1 '"nodeTypes"'

4. Test AI Generation Copy Section

1. Build the extension: npm run build
2. Test AI workflow generation with the new schema
3. Verify generated workflows are valid

Validation Rules Mapping Copy Chapter

Common Maintenance Tasks Copy Chapter

Deprecating a Node Type Copy Section

1. Mark as deprecated in TypeScript:

   typescript Copy

   export enum NodeType {
     Branch = 'branch', // @deprecated Use IfElse or Switch instead
   }

2. Do NOT remove from schema immediately (backward compatibility)

3. Add deprecation notice in schema:

   json Copy

   {
     "branch": {
       "description": "DEPRECATED: Use ifElse or switch instead. Maintained for backward compatibility.",
       "deprecated": true
     }
   }

Changing Field Constraints Copy Section

1. Update VALIDATION_RULES in TypeScript
2. Update corresponding maxLength, minLength, pattern, etc. in schema
3. Update example workflows if needed to comply with new constraints

Optimizing Schema Size Copy Section

The schema is used as AI context, so keep it under 15KB:

• Use concise descriptions
• Avoid redundant examples
• Compress JSON (no pretty-printing for production)
• Remove deprecated nodes after grace period (6+ months)

File Size Target Copy Chapter

• Target: < 10KB (allows room for growth)
• Current: ~11KB (acceptable)
• Maximum: 15KB (beyond this, consider splitting)

If schema exceeds 15KB, consider:

• Moving examples to separate file
• Creating focused schemas per use case
• Removing legacy/deprecated content

Checklist Copy Chapter

When making schema changes, verify:

• All NodeType enum values are documented in schema
• All VALIDATION_RULES values match schema constraints
• Example workflows use valid node types and connections
• Schema is valid JSON (python3 -m json.tool < resources/workflow-schema.json)
• File size is acceptable (< 15KB)
• AI generation tests pass
• TypeScript compilation succeeds (npm run compile)

Related Files Copy Chapter

• src/extension/services/schema-loader-service.ts - Loads schema for AI context
• src/extension/utils/validate-workflow.ts - Validates AI-generated workflows
• src/extension/commands/ai-generation.ts - Constructs prompts with schema

Questions? Copy Chapter

For questions or issues with schema maintenance, refer to:

• Design doc: /specs/001-ai-workflow-generation/plan.md
• Type definitions: src/shared/types/workflow-definition.ts
• Validation logic: src/extension/utils/validate-workflow.ts

File: packages/vscode/resources/README.md Copy Chapter

Extension Resources

Icon Copy Chapter

The extension icon (icon.png) should be:

• Size: 128x128 pixels
• Format: PNG with transparency
• Design: Represents workflow/automation (e.g., connected nodes, flowchart elements)
• Colors: Professional, matches Claude branding if applicable

Icon Placeholder Copy Section

Currently using a placeholder. To add a custom icon:

1. Create a 128x128 PNG image
2. Save as resources/icon.png
3. The package.json is already configured to use it

Design Suggestions Copy Section

• Visual workflow representation (nodes connected with arrows)
• Gear/cog with network connections
• Flow diagram icon
• Claude logo integrated with workflow elements

Note: Actual icon file needs to be created by a designer or using design tools.

File: packages/vscode/README.md Copy Chapter

CC Workflow Studio

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

Design workflows on a canvas. Export as Markdown your AI agent already understands. No more prompt-guessing.

Supported Agents Copy Chapter

Note: Agents other than Claude Code require activation from Toolbar's More menu.

Key Features Copy Chapter

🔀 Visual Workflow Editor - Intuitive drag-and-drop canvas for designing AI agent orchestrations without code

🤖 Agentic Engineering - Design multi-agent workflows with Sub-Agent orchestration, Agent Skills, and MCP tool integration — the building blocks of agentic engineering

✨ Edit with AI - Iteratively improve workflows through conversational AI - ask for changes, add features, or refine logic with natural language feedback

⚡ One-Click Export & Run - Export workflows to ready-to-use formats and run directly from the editor

How to Use Copy Chapter

Launch the Extension Copy Section

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

Create a Workflow Copy Section

• Add nodes from the palette and configure their settings, or use Edit with AI.

Save & Load Copy Section

• Click Save button in the toolbar to store your workflow as .vscode/workflows/*.json
• Click Load button in the toolbar to open a saved .json workflow

Export & Run Copy Section

• Click Export button in the toolbar to create a .md slash command or agent skill (use /workflow-name in AI coding agents)
• Click Run button in the toolbar to run your workflow directly in AI coding agents

Edit with AI Copy Section

• Click Edit with AI button in the toolbar to generate or refine workflows with natural language
• Native with MCP Server: Click an AI agent button in the Edit with AI panel to launch native AI editing. The MCP server starts automatically behind the scenes.

sequenceDiagram
    actor User
    box VS Code (CC Workflow Studio)
        participant UI as Editor UI
        participant MCP as MCP Server
    end
    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_workflow
        MCP-->>Agent: workflow JSON
        Agent->>MCP: apply_workflow
        MCP->>UI: Update canvas
    end

Usage Examples Copy Chapter

Coming soon - Sample workflows and tutorials are under development.

Use without VSCode Copy Chapter

The extension is one of three entry points to the same workflow JSON. Outside VSCode you can drive the canvas through:

• @cc-wf-studio/cli — ccwf preview opens a read-only browser viewer for any workflow file, ccwf export / ccwf run materialise it as Agent Skills, ccwf canvas runs the full editor in a localhost browser.
• @cc-wf-studio/mcp — the same MCP tools this extension exposes to in-canvas AI editing, available standalone via npx @cc-wf-studio/mcp --file <workflow.json> so an external Claude Code (or any MCP client) can read and edit your workflows.

Same workflow.json, three interfaces. See the monorepo README for the full story.

License Copy Chapter

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later).

See the LICENSE file for the full license text.

What this means Copy Section

• You can use, modify, and distribute this software
• If you modify and deploy this software (including as a network service), you must:
  • Make your modified source code available under AGPL-3.0
  • Provide access to the source code for users interacting with the service
• Commercial use is allowed, but proprietary modifications are not

Copyright (c) 2025 breaking-brake

Star History Copy Chapter

Acknowledgments Copy Chapter

Built with React Flow • Powered by Claude Code • Inspired by Dify

Made with CC Workflow Studio

File: packages/mcp/README.md Copy Chapter

@cc-wf-studio/mcp

MCP (Model Context Protocol) server toolkit for cc-wf-studio workflows. Ships tool definitions, an IO adapter contract, and a standalone stdio bin (ccwf-mcp) that AI clients can use to edit workflow JSON files without the VSCode canvas.

One of the three interfaces sharing a workflow file: this MCP server, the @cc-wf-studio/cli, and the cc-wf-studio VSCode extension. See the monorepo README for the bigger picture.

The package is the deduplicated home of the 6 cc-wf-studio MCP tools. Both the VSCode extension (canvas mode, HTTP transport) and the standalone bin (file mode, stdio transport) configure the same tool registrations through a shared factory.

Install Copy Chapter

# Run the standalone bin without installing
npx @cc-wf-studio/mcp --file path/to/workflow.json

# Or add to a local dev dependency
pnpm add -D @cc-wf-studio/mcp

CLI usage Copy Chapter

ccwf-mcp --file ./.vscode/workflows/my-workflow.json

Options:

The bin speaks stdio MCP — point an MCP client (Claude Code, MCP Inspector, …) at it. Example config for Claude Code's .mcp.json:

{
  "servers": {
    "cc-wf-studio": {
      "type": "stdio",
      "command": "npx",
      "args": ["@cc-wf-studio/mcp", "--file", ".vscode/workflows/my-workflow.json"]
    }
  }
}

Tools Copy Chapter

Library usage (custom adapters) Copy Chapter

import { createWorkflowMcpServer, type WorkflowIoAdapter } from '@cc-wf-studio/mcp';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const adapter: WorkflowIoAdapter = {
  /* implement the 6 methods */
};

const server = createWorkflowMcpServer(adapter);
await server.connect(new StdioServerTransport());

The FileWorkflowAdapter and the VSCode extension's McpServerManager are the two adapters that ship in the monorepo today.

File-mode behaviour notes Copy Chapter

• revision is sha256:<hex> of the file contents (UTF-8). apply_workflow refuses the write when expectedRevision doesn't match the current hash.
• Writes are atomic (temp file + rename).
• planAndPersistSubAgentFiles returns []. AI clients should supply complete commandFilePath on subAgent nodes when targeting the file mode — auto-creation of .claude/agents/*.md is intentionally left to canvas mode for now.

License Copy Chapter

MIT. See LICENSE.

File: packages/core/README.md Copy Chapter

@cc-wf-studio/core

Pure logic shared by every cc-wf-studio interface — the VSCode extension, the MCP server, and the ccwf CLI all reach for the same workflow types, validators, and Markdown/Mermaid generators that live here. No file system, no UI, no network: a node-side dependency you can pull into your own automation without inheriting an editor.

This is the "brain" of the monorepo. See the root README for how the three interfaces compose around it.

Install Copy Chapter

npm install @cc-wf-studio/core

What's inside Copy Chapter

Anything tied to a side-effect (fs.writeFile, vscode.window.*, postMessage, ...) lives in the caller — core only computes.

Usage Copy Chapter

import {
  generateMermaidFlowchart,
  generateExecutionInstructions,
  planWorkflowExportFiles,
  planAgentSkillFiles,
  validateAIGeneratedWorkflow,
  migrateWorkflow,
  type Workflow,
} from '@cc-wf-studio/core';

// 1. Validate before doing anything else.
const result = validateAIGeneratedWorkflow(rawJson);
if (!result.valid) {
  throw new Error(`Bad workflow:\n${result.errors.map((e) => e.message).join('\n')}`);
}

const workflow = migrateWorkflow(rawJson) as Workflow;

// 2. Render the canvas-equivalent Markdown.
const mermaid = generateMermaidFlowchart(workflow);
const guide = generateExecutionInstructions(workflow, { provider: 'claude-code' });

// 3. Decide what files to emit (without writing them).
const claudePlan = planWorkflowExportFiles(workflow);
// → [{ relativePath: '.claude/skills/<workflow>/SKILL.md', contents: ... }, ...]

const cursorPlan = planAgentSkillFiles(workflow, 'cursor');
// → [{ relativePath: '.cursor/skills/<workflow>/SKILL.md', ... },
//    { relativePath: '.cursor/agents/<sub-agent>.md', ... }]

Subpath imports Copy Chapter

@cc-wf-studio/core/mcp exposes a few McpNode-specific types (McpNodeData, ToolParameter) that pre-date the unified workflow-definition schema and still drift in shape. Reach for them only when working with MCP nodes specifically.

import { type McpNodeData } from '@cc-wf-studio/core/mcp';

@cc-wf-studio/core/resources/workflow-schema.json and …/workflow-schema.toon expose the raw schema files so a host can hand them to an LLM verbatim — the MCP server's get_workflow_schema tool does exactly that.

License Copy Chapter

MIT

File: packages/cli/README.md Copy Chapter

@cc-wf-studio/cli

Command-line tool (ccwf) for cc-wf-studio workflows. Renders, validates, materialises, and serves a workflow JSON from a terminal — no VSCode required.

One of the three interfaces sharing a workflow file: this CLI, the @cc-wf-studio/mcp stdio server, and the cc-wf-studio VSCode extension. See the monorepo README for the bigger picture.

Install Copy Chapter

# Run without installing
npx @cc-wf-studio/cli --help

# Or install locally
pnpm add -D @cc-wf-studio/cli

Subcommands Copy Chapter

`ccwf render` Copy Section

ccwf render ./.vscode/workflows/my-workflow.json            # Markdown (default)
ccwf render ./.vscode/workflows/my-workflow.json -f mermaid # ```mermaid block only

`ccwf validate` Copy Section

ccwf validate ./.vscode/workflows/my-workflow.json          # exit 0/1
ccwf validate ./.vscode/workflows/my-workflow.json --json   # prints { valid, errors[] }

`ccwf mcp` Copy Section

ccwf mcp --file ./.vscode/workflows/my-workflow.json

Speaks stdio MCP. Point an MCP client (Claude Code, MCP Inspector, …) at it. Equivalent to the standalone ccwf-mcp bin shipped by @cc-wf-studio/mcp — same factory, same tools.

Example .mcp.json:

{
  "servers": {
    "cc-wf-studio": {
      "type": "stdio",
      "command": "npx",
      "args": ["@cc-wf-studio/cli", "mcp", "--file", ".vscode/workflows/my-workflow.json"]
    }
  }
}

`ccwf export` Copy Section

ccwf export ./my-workflow.json                                # --agent claude-code (default)
ccwf export ./my-workflow.json --agent cursor                  # cursor
ccwf export ./my-workflow.json --agent codex --cwd /tmp/proj   # codex into a different root
ccwf export ./my-workflow.json --overwrite                     # replace existing files

Output layout by target agent:

.claude/commands/ is the previous home for the workflow entry; Claude Code is folding it into .claude/skills/, where each skill is a directory containing SKILL.md (see the Agent Skills format). ccwf export --agent claude-code writes to the new directory-based layout. Existing .claude/commands/<workflow>.md files are not deleted automatically.

The body of SKILL.md is, for now, still produced by the legacy SlashCommand generator — so its frontmatter retains fields like hooks, model, and argument-hint that the Skill spec doesn't strictly recognise. Migrating that body to a pure Skill format (and deciding what to do with the SlashCommand-only options) is a follow-up task.

`ccwf run` Copy Section

ccwf run ./my-workflow.json                                    # same files as export, plus a hint
ccwf run ./my-workflow.json --agent cursor                     # forwarded to export

ccwf run is a thin wrapper over ccwf export (same flags: --agent, --cwd, --overwrite). It adds an agent-specific "next step" line to stdout. With --launch (best-effort, claude-code only for now) it also walks PATH for the claude binary and spawns it in the output directory — when the binary is missing or a different agent is selected, the spawn is skipped and a warning is printed.

ccwf run ./my-workflow.json --launch        # write + spawn claude
ccwf run ./my-workflow.json --agent cursor  # write only (cursor launch not yet wired)

`ccwf preview` Copy Section

ccwf preview ./my-workflow.json                 # boot, print URL, open browser
ccwf preview ./my-workflow.json --port 51234    # pin to a port
ccwf preview ./my-workflow.json --keep-alive    # don't auto-shutdown when the tab closes

By default the server auto-shuts down 30 seconds after the last viewer tab closes, so you don't leak listeners after a one-off "open and read" session. The countdown only starts once at least one browser has actually connected — a run where the browser fails to launch and the user never opens the URL stays alive indefinitely. Pass --keep-alive to keep the server running until you hit Ctrl+C (useful for multiple tabs, LAN sharing, or reconnecting later).

Read-only viewer powered by the WorkflowOverview component the VSCode extension already ships:

• Left: Mermaid flow rendered from the workflow nodes / connections.
• Right: Per-node Markdown instructions generated by @cc-wf-studio/core's overview formatter.

No editor, no Save button, no extension RPCs — the browser fetches a single static HTML, the workflow JSON is injected once at boot. A Server-Sent Events channel keeps the page in sync with disk: edits to the workflow file trigger an automatic reload.

Reachability: bound to the IPv4 loopback (127.0.0.1) by default — only this machine can reach the server. The printed URL says localhost for readability and both addresses resolve to the same listener. The entry URL and SSE channel use a per-session UUID path prefix (http://localhost://) so two concurrent preview sessions don't collide; requests without the prefix get a 403. Pass --host (e.g. 0.0.0.0) only when you intentionally want other machines on the network (Docker, DevContainers, Codespaces, a colleague's laptop on the same LAN, …) to reach the preview — the banner prints an explicit non-loopback notice when that happens.

`ccwf canvas` (experimental) Copy Section

ccwf canvas ./my-workflow.json                # boot, print URL, open browser
ccwf canvas ./my-workflow.json --port 51234   # pin to a port

ccwf canvas brings up the full editable cc-wf-studio canvas in a browser. It serves the bundled webview UI from a local HTTP + WebSocket server; saves from the canvas write back to the same workflow file. Other VSCode-only features (Slack share, Claude API upload, MCP server management, agent-specific export buttons, …) intentionally return a CANVAS_UNSUPPORTED error so the UI surfaces the limitation rather than hanging.

Status: experimental. The intent is to keep the in-VSCode experience reachable without VSCode for use cases like remote SSH or CI environments. For "just look at this workflow" the upcoming ccwf preview (read-only Mermaid + Markdown view) will be lighter — it skips the WebSocket and just renders the WorkflowOverview component statically.

Reachability: the server binds to the IPv4 loopback (127.0.0.1) by default — only this machine can reach the server. The printed URL says localhost and both addresses resolve to the same listener. The entry URL and WebSocket use a per-session UUID path prefix (http://localhost://, ws://localhost://ws) so two concurrent sessions don't collide; requests without the prefix get a 403. Pass --host (e.g. 0.0.0.0) only when you intentionally want other machines on the network to reach the canvas — the banner prints an explicit non-loopback notice when that happens.

The bundled webview's VSCode message protocol is emulated by a small polyfill (bootstrap.js) injected into index.html. The webview source is unchanged — window.acquireVsCodeApi returns a WebSocket-backed transport that talks to this CLI process.

`ccwf install-skills` / `ccwf uninstall-skills` Copy Section

ccwf install-skills                  # ~/.claude/skills/ccwf-cli (user-scope, default)
ccwf install-skills --project        # ./.claude/skills/ccwf-cli (commit to share with the team)
ccwf install-skills --overwrite      # replace an existing copy
ccwf install-skills --dry-run        # print paths, write nothing

ccwf uninstall-skills                # remove the user-scope copy
ccwf uninstall-skills --project      # remove the project-scope copy
ccwf uninstall-skills --dry-run      # print deletions, write nothing

Installs a Claude Code Skill that teaches AI agents (Claude Code in particular) when to reach for ccwf and which subcommand fits each user phrasing. The skill auto-triggers when the user mentions viewing, validating, executing, or converting a workflow file — Claude then runs ccwf through Bash without per-command permission prompts (the skill whitelists Bash(ccwf:*) via allowed-tools).

After installing, open or restart your Claude Code session so the skill loads.

To refresh after upgrading the CLI, chain the two commands: ccwf uninstall-skills && ccwf install-skills. uninstall-skills is idempotent (a no-op when the destination is already empty).

Fixtures Copy Chapter

fixtures/sample-workflow.json is a minimal, schema-valid workflow that backs the smoke tests in this package's README examples.

Development Copy Chapter

Inside the monorepo, three invocation paths are available:

# 1. tsx — runs straight from src, no rebuild required (fastest iteration)
pnpm ccwf:dev render packages/cli/fixtures/sample-workflow.json

# 2. built dist — exercises the actual published code path
pnpm -F @cc-wf-studio/cli build
pnpm ccwf render packages/cli/fixtures/sample-workflow.json

# 3. via the hoisted bin — same as path 2, but uses the linked bin under node_modules/.bin
pnpm exec ccwf render packages/cli/fixtures/sample-workflow.json

Use ccwf:dev while iterating on a subcommand; use ccwf (built) before pushing to confirm the bin shipped under dist/ still works.

License Copy Chapter

MIT. See LICENSE.

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

File: README.md Copy Chapter

Claude Code Workflow Studio 開発ブログ

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

📖 About Copy Chapter

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

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

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

🔗 関連リンク Copy Chapter

• 本体リポジトリ: breaking-brake/cc-wf-studio
• ブログサイト: https://breaking-brake.github.io/
• Claude Code 公式: Anthropic Claude Code

🛠️ 技術スタック Copy Chapter

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

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

🚀 開発 Copy Chapter

セットアップ Copy Section

# リポジトリのクローン
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 を開いてサイトを確認できます。

利用可能なコマンド Copy Section

📝 ブログ記事の追加 Copy Chapter

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

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

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

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

ここに記事の本文を記述します...

3. 開発サーバーで確認：

npm run dev

4. 確認後、コミットしてプッシュ：

git add src/content/blog/006-new-article.md
git commit -m "feat: Add new blog article"
git push

🗂️ プロジェクト構造 Copy Chapter

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                # 依存関係

🚢 デプロイ Copy Chapter

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

自動デプロイ Copy Section

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

手動デプロイ Copy Section

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

🤝 コントリビューション Copy Chapter

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

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 をご覧ください。

📄 ライセンス Copy Chapter

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

📞 サポート Copy Chapter

• 問題報告: GitHub Issues
• ディスカッション: GitHub Discussions

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

File: docs/index.md Copy Chapter

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