bitrise-workflow-editor: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code (claude.ai/code) working in this repository.

@./node_modules/@bitrise/bitkit-v2/AGENTS.md

The one idea

The editor holds one YAML document as an AST in a Zustand store and lets people edit it through a dozen typed UIs instead of a text box. Pages read from the document, services mutate it, the Go server validates and persists it. Secrets, stacks, license pools and the step catalog live outside that document with their own fetch and save paths, which is the other half of docs/domain.md.

That "one document" is sometimes a tree of files linked by include:, and then it is a binding to the active file rather than the whole config. Every service still works, and every service reaches only that far, so a cascade written without knowing this leaves sibling files dangling and its own safety check reassures you (why).

It ships two ways: as a Bitrise CLI plugin (MODE=CLI, the default) and as a website inside the Bitrise monolith (MODE=WEBSITE).

Which doc answers your question

Question	Doc
How does X work?	docs/flows.md, seven paths with diagrams
What does this word mean, and what is guaranteed?	docs/domain.md
Why is it like this, may I change it, and what does this error mean?	docs/decisions.md, including a symptom index
How do I write code here?	docs/conventions.md

Read domain.md before designing anything that adds an entity, a reference between entities, or a cascade. Read decisions.md before changing something that looks odd, because it usually looks that way on purpose.

Debugging something? docs/decisions.md opens with a symptom table, and grep -rn '\*\*Trap\.\*\*' docs/ lists every known hazard in the set.

Those four cover what the source cannot tell you: rationale, and hazards that only appear at runtime. Service surfaces, model fields and file maps are deliberately absent. Read the code, it is right there and it does not go stale.