takt-ccwf-bridge

日本語

Converts Takt workflow YAML to cc-wf-studio workflow.json, so you can view and lay out a Takt workflow in an unmodified cc-wf-studio (ccwf preview / the VSCode extension).

takt YAML ──to-ccwf──▶ workflow.json ──▶ ccwf preview / VSCode extension (view + layout)

A to-takt command (JSON → YAML) also exists for verification and for programmatically patching hand-edited JSON. It is not a supported "edit on the canvas, write back to Takt" workflow — see Known limitations.

Install

npm install -g takt-ccwf-bridge   # or run ad hoc with: npx takt-ccwf-bridge

Requires Node.js >= 20.

Usage

# Takt YAML → cc-wf-studio workflow.json (the primary, supported direction)
takt-ccwf to-ccwf my-workflow.yaml -o my-workflow.ccwf.json

# Reuse node positions from a previously saved canvas layout
takt-ccwf to-ccwf my-workflow.yaml --layout previous.ccwf.json

Preview the result with cc-wf-studio:

npx @cc-wf-studio/cli preview my-workflow.ccwf.json

to-takt and roundtrip also exist (JSON → YAML, patch-based, byte-identical on an unchanged file) but are for verification / hand-edited JSON, not for canvas-edit write-back — see Known limitations:

takt-ccwf to-takt my-workflow.ccwf.json --base my-workflow.yaml -o my-workflow.yaml
takt-ccwf to-takt my-workflow.ccwf.json --base my-workflow.yaml --sync-conditions
takt-ccwf roundtrip my-workflow.yaml

Try it

Pre-converted samples are included under examples/ so you can preview without converting anything yourself first:

npx @cc-wf-studio/cli preview examples/default.ccwf.json       # simple flow + workflow_call
npx @cc-wf-studio/cli preview examples/peer-review.ccwf.json   # parallel branches

This opens a browser canvas. You should see nodes named after each Takt step, edges for each rules condition, and a COMPLETE/ABORT end node — that's the same view to-ccwf produces for your own workflows. examples/*.ccwf.json were generated from fixtures/takt/en/default.yaml and fixtures/takt/en/peer-review.yaml via:

takt-ccwf to-ccwf fixtures/takt/en/default.yaml -o examples/default.ccwf.json
takt-ccwf to-ccwf fixtures/takt/en/peer-review.yaml -o examples/peer-review.ccwf.json

Compatibility

Built and verified against:

• Takt 0.51.0 (latest stable; fixtures/takt/ is byte-identical to the workflow YAML bundled with this release)
• cc-wf-studio [email protected] / [email protected], workflow schema 1.0.0 (reference/cc-wf-studio/workflow-schema.json)
• cc-wf-studio VSCode extension 3.35.1 (for the canvas-save behavior noted in Known limitations)

Takt's workflow YAML format isn't formally versioned; both projects are moving targets, so a newer Takt or cc-wf-studio release may not convert cleanly. If you hit a schema mismatch, please open an issue with your Takt version (takt --version) and the failing YAML.

Design

• Every Takt step is embedded verbatim in the node's x-takt field — x-takt is the source of truth for the round trip; connections are display-only.
• to-takt applies changes as a patch against the original YAML document, so an unchanged workflow round-trips byte-identically (comments and key order included).
• Unknown fields are always passed through; nothing is dropped as "unsupported".

See docs/mapping.md for the full mapping design.

Known limitations

• There is no working "edit on the canvas, write back to Takt" flow. Saving from the cc-wf-studio canvas drops all edge conditions (verified against cc-wf-studio CLI and VSCode extension 3.35.1). Treat the canvas as a viewer and layout tool only; edit workflow logic in the Takt YAML directly. --sync-conditions is only useful for hand-edited JSON or future upstream versions that fix this.
• Node names are rebuilt on canvas save; non-ASCII workflow names are not accepted by cc-wf-studio. See the loss table in docs/mapping.md.

Development

npm install
npm run typecheck && npm test
npm run cli -- to-ccwf fixtures/takt/en/default.yaml

Test fixtures under fixtures/takt/ are copies of the built-in workflow library shipped with Takt (MIT). reference/cc-wf-studio/workflow-schema.json is copied from cc-wf-studio (MIT, from the core package).

License

MIT