create-byan-agent 2.19.2 → 2.20.0

package/install/templates/.claude/workflows/create-excalidraw-dataflow.js

@@ -0,0 +1,214 @@
+export const meta = {
+  name: 'create-excalidraw-dataflow',
+  description: 'Native port of the BYAN create-excalidraw-dataflow workflow: build a Data Flow Diagram (DFD) in Excalidraw .excalidraw JSON format. Mirrors the 10 source steps (contextual analysis -> level -> requirements -> theme -> plan -> load resources -> build elements -> optimize/save -> validate JSON -> validate content) and returns a structured verdict for the orchestrating skill to present at the human gate.',
+  phases: [
+    { title: 'CONTEXT', detail: 'step 0 - contextual analysis of the DFD request' },
+    { title: 'PLAN', detail: 'steps 1-4 - resolve level, requirements, theme, and plan the DFD structure' },
+    { title: 'RESOURCES', detail: 'step 5 - load templates, library, theme, helpers' },
+    { title: 'BUILD', detail: 'step 6 - build DFD elements per standard notation' },
+    { title: 'SAVE', detail: 'step 7 - optimize, strip deleted, save the .excalidraw file' },
+    { title: 'VALIDATE_JSON', detail: 'step 8 - JSON.parse validation loop (fix-and-retry, never delete)' },
+    { title: 'VALIDATE_CONTENT', detail: 'step 9 - validate against checklist.md, return verdict' },
+  ],
+}
+
+// ---------------------------------------------------------------------------
+// FD / STRICT STATE CONTRACT (re-asserted inline).
+//
+// The in-CLI Workflow tool runs this script OUTSIDE the conversation turn, so
+// BYAN's main-thread hooks (fd-phase-guard, strict-scope-guard, strict-stop-
+// guard) DO NOT fire here. This script therefore:
+//   - NEVER imports/requires _byan/.../lib/fd-state.js and NEVER writes
+//     fd-state.json directly (forbidden by byan-lint-workflows.js).
+//   - uses NO wall-clock and NO randomness primitive (Date/RNG would
+//     break resume). Any timestamp/id is passed in via `args`.
+//   - returns DATA only. The orchestrating skill is the human-gated conductor;
+//     IT records FD/strict state via the byan_fd_* / byan_strict_* MCP tools
+//     AT the gate, and it owns the elicit="true" human decisions (DFD level,
+//     requirements, theme) that the source steps 1-3 prompt for.
+// The .excalidraw FILE is the workflow's product, written by the BUILD/SAVE
+// leaves — that is the artifact, not BYAN platform state.
+// ---------------------------------------------------------------------------
+
+// Source paths (workflow.yaml). The leaf agents read these real files; the
+// script never touches the filesystem itself.
+const ROOT = '/home/yan/BYAN'
+const INSTALLED = `${ROOT}/_byan/workflow/simple/excalidraw-diagrams/create-dataflow`
+const SHARED = `${ROOT}/_byan/workflow/simple/excalidraw-diagrams/_shared`
+const HELPERS = `${ROOT}/_byan/connaissance/excalidraw/excalidraw-helpers.md`
+const JSON_VALIDATION = `${ROOT}/_byan/connaissance/excalidraw/validate-json-instructions.md`
+const TEMPLATES = `${SHARED}/excalidraw-templates.yaml`
+const LIBRARY = `${SHARED}/excalidraw-library.json`
+const CHECKLIST = `${INSTALLED}/checklist.md`
+
+// Human-elicited inputs (source steps 1-3). Defaults keep the engine runnable
+// when the orchestrating skill has not yet resolved the gate; the skill should
+// pass these in args once the user has answered.
+const level = (args && args.level) || 'unspecified (resolve at human gate: context/level-0/level-1/level-2/custom)'
+const requirements = (args && args.requirements) || 'unspecified (resolve at human gate: processes, data stores, external entities)'
+const theme = (args && args.theme) || 'Standard DFD (process #e3f2fd, data store #e8f5e9, external entity #f3e5f5, border #1976d2)'
+// Timestamp MUST come from args (no Date in the sandbox). Source default_output_file
+// is dataflow-{timestamp}.excalidraw under {output_folder}/excalidraw-diagrams/.
+const stamp = (args && args.timestamp) || 'TIMESTAMP'
+const outputFile = (args && args.outputFile) ||
+  `${ROOT}/_byan-output/excalidraw-diagrams/dataflow-${stamp}.excalidraw`
+
+// JSON validation convergence guard (source step 8: re-run until pass, NEVER
+// delete the file). Bounded retry cap so the script cannot loop forever.
+const MAX_FIX_ATTEMPTS = 3
+
+const PLAN_SCHEMA = {
+  type: 'object',
+  required: ['processes', 'dataStores', 'externalEntities', 'dataFlows'],
+  properties: {
+    processes: { type: 'array', items: { type: 'string' }, description: 'numbered processes (1.0, 2.0, ...), verb phrases' },
+    dataStores: { type: 'array', items: { type: 'string' }, description: 'named data stores (D1, D2, ...), noun phrases' },
+    externalEntities: { type: 'array', items: { type: 'string' }, description: 'named external entities, noun phrases' },
+    dataFlows: { type: 'array', items: { type: 'string' }, description: 'labeled flows, source -> target with data name' },
+    notes: { type: 'string', description: 'layout / level notes' },
+  },
+}
+
+const JSON_VALIDATION_SCHEMA = {
+  type: 'object',
+  required: ['valid'],
+  properties: {
+    valid: { type: 'boolean', description: 'true ONLY if JSON.parse of the saved .excalidraw file succeeds' },
+    error: { type: 'string', description: 'parser error message and position when invalid' },
+  },
+}
+
+const CONTENT_SCHEMA = {
+  type: 'object',
+  required: ['pass', 'failedItems'],
+  properties: {
+    pass: { type: 'boolean', description: 'true only if every checklist.md item is satisfied' },
+    failedItems: { type: 'array', items: { type: 'string' }, description: 'checklist items not satisfied' },
+    summary: { type: 'string', description: 'one-line content-validation status' },
+  },
+}
+
+// --- Step 0: Contextual Analysis -------------------------------------------
+phase('CONTEXT')
+const context = await agent(
+  `You are the create-excalidraw-dataflow workflow (BMad). Read the source spec at ` +
+    `${INSTALLED}/instructions.md and ${INSTALLED}/workflow.yaml.\n` +
+    `STEP 0 (Contextual Analysis): from the request, extract what is already known about the DFD: ` +
+    `level, processes, data stores, external entities, data flows. ` +
+    `Request level=${JSON.stringify(level)}; requirements=${JSON.stringify(requirements)}. ` +
+    `Report which of (level, processes, data stores, external entities) are clear and which are missing. ` +
+    `Per the source, if ALL requirements are clear we may skip directly to structure planning.`,
+  { label: 'context-analysis', phase: 'CONTEXT' }
+)
+
+// --- Steps 1-4: Level, Requirements, Theme, Plan structure -----------------
+// Source steps 1-3 are elicit="true" (human input). The orchestrating skill
+// owns those decisions and passes the answers via args; here we consolidate
+// the resolved inputs and produce the concrete DFD structure (step 4).
+phase('PLAN')
+const plan = await agent(
+  `STEP 1-4 of create-excalidraw-dataflow. Context analysis: ${context}\n` +
+    `Resolved human inputs (source steps 1-3 elicit): level=${JSON.stringify(level)}; ` +
+    `requirements=${JSON.stringify(requirements)}; theme=${JSON.stringify(theme)}.\n` +
+    `STEP 4 (Plan DFD Structure): produce the concrete plan. ` +
+    `List processes numbered 1.0/2.0..., data stores D1/D2..., external entities, and every data flow ` +
+    `(source -> target, labeled with the data name). Respect DFD rules: no direct flow between two external ` +
+    `entities, no direct flow between two data stores. Match the chosen DFD level. ` +
+    `Read ${HELPERS} for standard DFD notation if needed.`,
+  { label: 'plan-structure', phase: 'PLAN', schema: PLAN_SCHEMA }
+)
+
+// --- Step 5: Load Resources -------------------------------------------------
+phase('RESOURCES')
+const resources = await agent(
+  `STEP 5 (Load Resources) of create-excalidraw-dataflow. ` +
+    `Load and summarize the materials needed to build the diagram:\n` +
+    `- templates: ${TEMPLATES} (extract the \`dataflow\` section)\n` +
+    `- library: ${LIBRARY}\n` +
+    `- theme: ${JSON.stringify(theme)} (use existing theme.json if present, else this scheme)\n` +
+    `- helpers: ${HELPERS} (standard DFD notation + Excalidraw element shapes)\n` +
+    `Report the element templates (process ellipse, data-store rectangle/parallel-lines, external-entity ` +
+    `rectangle, labeled-arrow) and the color/stroke values you will apply. Plan structure: ${JSON.stringify(plan)}`,
+  { label: 'load-resources', phase: 'RESOURCES' }
+)
+
+// --- Step 6: Build DFD Elements --------------------------------------------
+phase('BUILD')
+const built = await agent(
+  `STEP 6 (Build DFD Elements) of create-excalidraw-dataflow. Resources: ${resources}\n` +
+    `Build the full Excalidraw element set following standard DFD notation, in this build order: ` +
+    `(1) external entities as rectangles with bold border; (2) processes as circles/ellipses carrying their ` +
+    `number (1.0, 2.0, verb phrases); (3) data stores as parallel lines or rectangles (D1, D2, noun phrases); ` +
+    `(4) data flows as labeled arrows showing direction. ` +
+    `Layout: external entities at the edges, processes in the center, data stores between processes, ` +
+    `minimize crossing flows, left-to-right or top-to-bottom. ` +
+    `Apply the theme colors. Bind arrows to their endpoints and group related elements. ` +
+    `Produce a complete Excalidraw scene object (type "excalidraw", version, source, elements[], appState, files{}).`,
+  { label: 'build-elements', phase: 'BUILD' }
+)
+
+// --- Step 7: Optimize and Save ---------------------------------------------
+phase('SAVE')
+const saved = await agent(
+  `STEP 7 (Optimize and Save) of create-excalidraw-dataflow. Built scene: ${built}\n` +
+    `Verify DFD-rule compliance (numbered processes, labeled flows, no entity->entity or store->store direct flow). ` +
+    `Strip unused elements and any element with isDeleted: true. ` +
+    `Write the final .excalidraw JSON to: ${outputFile}. Confirm the file was written.`,
+  { label: 'optimize-save', phase: 'SAVE' }
+)
+
+// --- Step 8: Validate JSON Syntax (bounded fix-and-retry, never delete) -----
+phase('VALIDATE_JSON')
+let jsonCheck = { valid: false, error: 'not yet validated' }
+let fixAttempts = 0
+while (true) {
+  jsonCheck = await agent(
+    `STEP 8 (Validate JSON Syntax) of create-excalidraw-dataflow. Attempt ${fixAttempts + 1}/${MAX_FIX_ATTEMPTS + 1}.\n` +
+      `Validate the saved file with: node -e "JSON.parse(require('fs').readFileSync('${outputFile}','utf8')); console.log('valid')". ` +
+      `Guidance: ${JSON_VALIDATION}. ` +
+      `CRITICAL: NEVER delete the file on failure. If JSON.parse fails, read the error position, open the file, ` +
+      `fix the exact syntax error (missing comma/bracket/quote), save, and report valid=false with the error. ` +
+      `If it parses, report valid=true. Save context: ${saved}`,
+    { label: `validate-json-${fixAttempts + 1}`, phase: 'VALIDATE_JSON', schema: JSON_VALIDATION_SCHEMA }
+  )
+  log(`json validation attempt ${fixAttempts + 1}: valid=${Boolean(jsonCheck && jsonCheck.valid)}`)
+  if (jsonCheck && jsonCheck.valid) break
+  fixAttempts += 1
+  if (fixAttempts > MAX_FIX_ATTEMPTS) break
+}
+
+// --- Step 9: Validate Content (against checklist.md) ------------------------
+phase('VALIDATE_CONTENT')
+const contentCheck = await agent(
+  `STEP 9 (Validate Content) of create-excalidraw-dataflow. ` +
+    `JSON valid=${Boolean(jsonCheck && jsonCheck.valid)}. ` +
+    `Validate the saved diagram (${outputFile}) against EVERY item in the checklist at ${CHECKLIST}: ` +
+    `DFD notation (process ellipses, data-store parallel-lines/rectangles, external-entity rectangles, labeled ` +
+    `arrows), structure (numbered processes, labeled flows, named stores/entities), completeness (all I/O accounted, ` +
+    `no orphaned processes, data conservation, level appropriate), layout (logical direction, minimal crossings, ` +
+    `balanced, grid-aligned), and technical quality (grouped, bound arrows, readable text, no isDeleted:true, valid JSON, ` +
+    `saved to correct location). List any item not satisfied.`,
+  { label: 'validate-content', phase: 'VALIDATE_CONTENT', schema: CONTENT_SCHEMA }
+)
+
+// Return DATA only. The orchestrating skill presents this verdict at the human
+// gate and records FD/strict state via MCP.
+const jsonValid = Boolean(jsonCheck && jsonCheck.valid)
+const contentPass = Boolean(contentCheck && contentCheck.pass)
+return {
+  workflow: 'create-excalidraw-dataflow',
+  summary: jsonValid && contentPass
+    ? 'DFD built, saved, JSON-valid, and checklist-compliant'
+    : 'DFD produced but validation incomplete - see jsonValid/contentCheck',
+  outputFile,
+  level,
+  steps: 10,
+  plan,
+  jsonValid,
+  jsonFixAttempts: fixAttempts,
+  maxFixAttempts: MAX_FIX_ATTEMPTS,
+  contentPass,
+  failedChecklistItems: (contentCheck && contentCheck.failedItems) || [],
+  needsHumanGate: true,
+  result: contentCheck,
+}

package/install/templates/.claude/workflows/create-excalidraw-diagram.js

@@ -0,0 +1,188 @@
+export const meta = {
+  name: 'create-excalidraw-diagram',
+  description: 'Native port of the BYAN create-diagram (excalidraw) pipeline workflow: turn a confirmed diagram spec (type, components, relationships, notation, theme) into a valid .excalidraw file via plan -> load-resources -> build elements -> optimize/save -> validate-JSON (bounded fix loop) -> validate-content. Elicitation gates (steps 1-4: diagram type, requirements, theme choice) stay OUTSIDE the script and arrive via args; the script returns a structured verdict for the orchestrating skill to present at the human gate.',
+  phases: [
+    { title: 'ANALYZE', detail: 'source step 0 - extract diagram type, components, relationships, notation from the confirmed spec' },
+    { title: 'PLAN', detail: 'source step 5 - list components/entities, map relationships, lay out the structure' },
+    { title: 'LOAD-RESOURCES', detail: 'source step 6 - load excalidraw templates/library/helpers and merge the chosen theme' },
+    { title: 'BUILD', detail: 'source step 7 - build shapes+labels (groupIds/containerId) and connections (start/endBinding) in the per-type build order on a 20px grid' },
+    { title: 'SAVE', detail: 'source step 8 - strip appState/files/isDeleted elements and write the .excalidraw file' },
+    { title: 'VALIDATE-JSON', detail: 'source step 9 - JSON.parse the saved file, fix syntax errors in place, re-validate up to a hard cap (NEVER delete the file)' },
+    { title: 'VALIDATE-CONTENT', detail: 'source step 10 - validate the diagram against the create-diagram checklist.md' },
+  ],
+}
+
+// ---------------------------------------------------------------------------
+// FD / STRICT STATE CONTRACT  (re-asserted inline — byan-lint-workflows).
+//
+// The in-CLI Workflow tool runs this script OUTSIDE the conversation turn, so
+// BYAN's main-thread hooks (fd-phase-guard, strict-scope-guard, strict-stop-
+// guard, mantra-validate) DO NOT fire here. This script therefore:
+//   - NEVER imports/requires _byan/.../lib/fd-state.js and NEVER writes
+//     fd-state.json directly  (enforced by byan-lint-workflows.js).
+//   - uses NO wall-clock and NO randomness primitive (wall-clock/RNG/
+//     crypto) — those break resume; any timestamp/id is passed via args.
+//   - returns DATA only. The orchestrating skill is the human-gated conductor;
+//     IT records FD/strict state via the byan_fd_* / byan_strict_* MCP tools
+//     AT the gate, and it owns the human decisions (steps 1-4 elicitation:
+//     diagram type, requirements, notation, theme choice).
+// The .excalidraw FILE is the workflow's product, written by the SAVE leaf —
+// that is the artifact, not BYAN platform state.
+// ---------------------------------------------------------------------------
+
+// Bounded JSON-fix loop guard — mirrors source step 9 ("repeat until validation
+// passes") but with a HARD cap so the sandbox cannot loop forever. The sandbox
+// forbids unbounded loops; this turns the prose rule into a real integer cap.
+const MAX_JSON_FIX_CYCLES = 5
+
+// Spec arrives pre-confirmed from the human gate (source steps 0-4). The script
+// never elicits; it consumes what the orchestrating skill collected.
+const diagramType = (args && args.diagramType) || 'system architecture'
+const spec = (args && args.spec) || 'components, relationships and notation as described by the user'
+const notation = (args && args.notation) || 'Standard'
+const theme = (args && args.theme) || 'Professional (Component #e3f2fd / Database #e8f5e9 / Service #fff3e0 / Border #1976d2)'
+// Timestamp/output path are passed in (no wall-clock in the sandbox).
+const outputFile =
+  (args && args.outputFile) ||
+  `_byan-output/excalidraw-diagrams/diagram-${(args && args.timestamp) || 'GATE-TIMESTAMP'}.excalidraw`
+
+const helpers = '_byan/connaissance/excalidraw/excalidraw-helpers.md'
+const jsonValidation = '_byan/connaissance/excalidraw/validate-json-instructions.md'
+const templates = '_byan/workflow/simple/excalidraw-diagrams/_shared/excalidraw-templates.yaml'
+const library = '_byan/workflow/simple/excalidraw-diagrams/_shared/excalidraw-library.json'
+const checklist = '_byan/workflow/simple/excalidraw-diagrams/create-diagram/checklist.md'
+
+// --- Source step 0: Contextual Analysis ------------------------------------
+phase('ANALYZE')
+const analysis = await agent(
+  `You are the create-excalidraw-diagram engine (BMad excalidraw pipeline), executing step 0 "Contextual Analysis".\n` +
+    `The diagram spec is ALREADY confirmed by the user at the human gate — do NOT re-ask anything.\n` +
+    `Diagram type: ${JSON.stringify(diagramType)}\n` +
+    `Spec (components/entities + relationships): ${JSON.stringify(spec)}\n` +
+    `Notation standard: ${JSON.stringify(notation)}\n` +
+    `From this, extract and report a normalized structured intent: the resolved diagram type, the exhaustive list of ` +
+    `components/entities, the exhaustive list of relationships (with direction), and the notation rules that apply ` +
+    `for that type. If the spec is contradictory or missing a relationship endpoint, flag it explicitly (do not invent).`,
+  { label: 'contextual-analysis', phase: 'ANALYZE' }
+)
+
+// --- Source step 5: Plan Diagram Structure ---------------------------------
+phase('PLAN')
+const plan = await agent(
+  `Step 5 "Plan Diagram Structure". Confirmed intent:\n${analysis}\n\n` +
+    `List ALL components/entities and map ALL relationships. Produce a concrete planned layout for a ${JSON.stringify(diagramType)}: ` +
+    `assign each element an (x,y) snapped to a 20px grid, keep 40px spacing between components and 60px between sections, ` +
+    `and pick the build order appropriate to the type (Architecture: Services -> Databases -> Connections -> Labels; ` +
+    `ERD: Entities -> Attributes -> Relationships -> Cardinality; UML Class: Classes -> Attributes -> Methods -> Relationships; ` +
+    `UML Sequence: Actors -> Lifelines -> Messages -> Returns; UML Use Case: Actors -> Use Cases -> Relationships). ` +
+    `Report the layout and the chosen build order. Do NOT draw yet.`,
+  { label: 'plan-structure', phase: 'PLAN' }
+)
+
+// --- Source step 6: Load Resources -----------------------------------------
+phase('LOAD-RESOURCES')
+const resources = await agent(
+  `Step 6 "Load Resources". Read these files and report what you will reuse:\n` +
+    `- templates: ${templates} (extract the \`diagram\` section)\n` +
+    `- library: ${library}\n` +
+    `- helpers (element-creation guidelines): ${helpers}\n` +
+    `Merge the chosen theme into the template. Theme = ${JSON.stringify(theme)}.\n` +
+    `Report the resolved template skeleton, the available library items, and the merged theme color map ` +
+    `(component fill, database fill, service fill, border/accent stroke, text stroke #1e1e1e, arrow stroke).`,
+  { label: 'load-resources', phase: 'LOAD-RESOURCES' }
+)
+
+// --- Source step 7: Build Diagram Elements ---------------------------------
+phase('BUILD')
+const built = await agent(
+  `Step 7 "Build Diagram Elements". CRITICAL: follow the helpers (${helpers}) exactly.\n` +
+    `Planned layout & build order:\n${plan}\n\nResources & merged theme:\n${resources}\n\n` +
+    `For EACH component: generate unique shape-id/text-id/group-id; create the shape with groupIds and ` +
+    `boundElements; compute text width = (text.length * fontSize * 0.6) + 20 rounded to 10; create the text with ` +
+    `containerId=shape-id, the SAME groupIds, textAlign=center, verticalAlign=middle. For EACH connection: choose ` +
+    `straight (forward flow) or elbow (upward/backward/complex) arrow, set startBinding and endBinding, and update ` +
+    `boundElements on BOTH connected shapes. Follow the build order from the plan, snap every (x,y) to the 20px grid, ` +
+    `apply theme colors consistently, and keep IDs unique. Report the full in-memory excalidraw element array.`,
+  { label: 'build-elements', phase: 'BUILD' }
+)
+
+// --- Source step 8: Optimize and Save --------------------------------------
+phase('SAVE')
+const saved = await agent(
+  `Step 8 "Optimize and Save". Element array:\n${built}\n\n` +
+    `Strip from the final output: the appState object, the files object (unless images are used), every element with ` +
+    `isDeleted:true, unused library items, and any version history. Then WRITE the optimized excalidraw document to ` +
+    `${JSON.stringify(outputFile)} (type "excalidraw", a valid version/source header, and the elements array). ` +
+    `Report the saved path and the final element count.`,
+  { label: 'optimize-save', phase: 'SAVE' }
+)
+
+// --- Source step 9: Validate JSON Syntax (bounded fix loop) -----------------
+phase('VALIDATE-JSON')
+const JSON_SCHEMA = {
+  type: 'object',
+  required: ['valid'],
+  properties: {
+    valid: { type: 'boolean', description: 'true ONLY if node -e JSON.parse on the saved file exits 0' },
+    error: { type: 'string', description: 'the syntax error message + position when not valid' },
+    fixed: { type: 'boolean', description: 'true if a syntax error was found and fixed this pass' },
+  },
+}
+let jsonCycles = 0
+let jsonResult = { valid: false, error: 'not started' }
+while (true) {
+  jsonCycles += 1
+  jsonResult = await agent(
+    `Step 9 "Validate JSON Syntax", pass ${jsonCycles}. CRITICAL: NEVER delete the file if validation fails — fix it.\n` +
+      `Follow ${jsonValidation}. Run exactly:\n` +
+      `  node -e "JSON.parse(require('fs').readFileSync('${outputFile}', 'utf8')); console.log('valid')"\n` +
+      `If it exits 0, set valid=true. If it exits 1, read the error message/position, open ${JSON.stringify(outputFile)} at ` +
+      `that location, fix the single syntax error indicated (missing/extra comma, bracket, brace or quote), SAVE, set ` +
+      `fixed=true and valid=false, and report the error. Do not re-run here; the loop re-invokes you.`,
+    { label: `validate-json-${jsonCycles}`, phase: 'VALIDATE-JSON', schema: JSON_SCHEMA }
+  )
+  log(`json pass ${jsonCycles}: valid=${Boolean(jsonResult && jsonResult.valid)}`)
+  if (jsonResult && jsonResult.valid) break
+  if (jsonCycles >= MAX_JSON_FIX_CYCLES) break
+}
+
+// --- Source step 10: Validate Content (checklist) --------------------------
+phase('VALIDATE-CONTENT')
+const CONTENT_SCHEMA = {
+  type: 'object',
+  required: ['pass'],
+  properties: {
+    pass: { type: 'boolean', description: 'true only if every checklist item is satisfied' },
+    failedItems: { type: 'array', items: { type: 'string' }, description: 'checklist items that are not satisfied' },
+    elementCount: { type: 'integer', description: 'final element count (must be under 80)' },
+    notes: { type: 'string' },
+  },
+}
+const content = await agent(
+  `Step 10 "Validate Content". Validate the saved diagram ${JSON.stringify(outputFile)} against the checklist at ${checklist}.\n` +
+    `Check element structure (matching groupIds, containerId on text, text width, alignment), layout (20px grid, 40/60px ` +
+    `spacing, no overlaps), connections (start/endBinding on every arrow, boundElements updated, clear relationship types), ` +
+    `notation/standards for ${JSON.stringify(diagramType)} (${JSON.stringify(notation)}), theme consistency, and output ` +
+    `quality (element count under 80, no isDeleted elements, valid JSON, correct save location). ` +
+    `Set pass=true only if EVERY item holds; otherwise list the failed items precisely.`,
+  { label: 'validate-content', phase: 'VALIDATE-CONTENT', schema: CONTENT_SCHEMA }
+)
+
+// Return DATA only. The orchestrating skill presents this at the human gate
+// ("Diagram created ... Open to view?") and records FD/strict state via MCP.
+return {
+  workflow: 'create-excalidraw-diagram',
+  diagramType,
+  notation,
+  theme,
+  outputFile,
+  jsonValid: Boolean(jsonResult && jsonResult.valid),
+  jsonFixCycles: jsonCycles,
+  maxJsonFixCycles: MAX_JSON_FIX_CYCLES,
+  contentPass: Boolean(content && content.pass),
+  failedChecklistItems: (content && content.failedItems) || [],
+  elementCount: content && content.elementCount,
+  steps: 7,
+  needsHumanGate: true,
+  result: { analysis, plan, resources, built, saved, json: jsonResult, content },
+}

package/install/templates/.claude/workflows/create-excalidraw-flowchart.js

@@ -0,0 +1,225 @@
+export const meta = {
+  name: 'create-excalidraw-flowchart',
+  description: 'Native port of the BYAN create-excalidraw-flowchart workflow: turn gathered flowchart requirements + theme into a valid .excalidraw file via a deterministic pipeline (plan layout -> load template/library/helpers -> build bound elements -> optimize & save -> JSON-validate with a bounded retry loop -> content-validate against the checklist), returning a verdict for the orchestrating skill to present at the human gate.',
+  phases: [
+    { title: 'CONTEXT', detail: 'mirror step 0/1: restate gathered requirements (type, complexity, decisions, output path)' },
+    { title: 'PLAN', detail: 'mirror step 4: plan the flowchart layout (steps + decision points)' },
+    { title: 'RESOURCES', detail: 'mirror step 5: load template flowchart section, library, helpers, merge theme colors' },
+    { title: 'BUILD', detail: 'mirror step 6: build shapes/diamonds/circles with labels and bound arrows' },
+    { title: 'SAVE', detail: 'mirror step 7: strip deleted elements and save to the output file' },
+    { title: 'VALIDATE_JSON', detail: 'mirror step 8: JSON.parse the file, fix syntax, re-validate (bounded retry)' },
+    { title: 'VALIDATE_CONTENT', detail: 'mirror step 9: validate against checklist.md' },
+    { title: 'VERDICT', detail: 'return a structured verdict to the orchestrating skill' },
+  ],
+}
+
+// ---------------------------------------------------------------------------
+// FD / STRICT STATE CONTRACT  (re-asserted inline — byan-lint-workflows).
+//
+// The in-CLI Workflow tool runs this script OUTSIDE the conversation turn, so
+// BYAN's main-thread hooks (fd-phase-guard, strict-scope-guard, strict-stop-
+// guard, mantra-validate) DO NOT fire here. This script therefore:
+//   - NEVER imports/requires _byan/.../lib/fd-state.js and NEVER writes
+//     fd-state.json directly (forbidden by the linter; no import/require/fs).
+//   - uses NO wall-clock and NO randomness primitive (wall-clock / RNG
+//     break resume); any timestamp/id arrives via `args`.
+//   - returns DATA only. The orchestrating skill is the human-gated conductor;
+//     IT records FD/strict state via the byan_fd_* / byan_strict_* MCP tools.
+// The .excalidraw FILE is this workflow's product (written by the BUILD/SAVE
+// leaves) — that is the artifact, not BYAN platform state.
+//
+// The interactive elicitation of the source (step 1 gather-requirements, step 2
+// reuse-theme, step 3 create-theme, step 4 structure-approval, step 8 "open to
+// view?") are HUMAN GATES. They stay OUT of the script: their answers arrive as
+// `args`, and the final open/approve decision is returned as a verdict.
+// ---------------------------------------------------------------------------
+
+// Convergence guard for step 8's JSON-validation retry. The source prose says
+// "Repeat until validation passes" (unbounded). Turn it into a real counter
+// with a hard cap so the loop cannot run forever in the sandbox.
+const MAX_FIX_CYCLES = 3
+function jsonFixGuard({ cycles, valid, maxCycles = MAX_FIX_CYCLES }) {
+  if (valid) return { done: true, abort: false, reason: 'valid-json' }
+  if (cycles >= maxCycles) return { done: true, abort: true, reason: `JSON still invalid after ${maxCycles} fix attempts` }
+  return { done: false, abort: false, reason: 'continue' }
+}
+
+// --- args (all gathered at the human gate by the orchestrating skill) --------
+// flowType        : "Business Process" | "Algorithm/Logic" | "User Journey" | "Data Pipeline" | "Other"
+// complexity      : "simple(3-5)" | "medium(6-10)" | "complex(11-20)" | "very-complex(20+)"
+// decisionPoints  : "none" | "few(1-2)" | "multiple(3-5)" | "complex(6+)"
+// outputFile      : absolute/relative path to the .excalidraw file to write
+// theme           : a theme.json-shaped object (primaryFill/accent/decision/text) or null
+const flowType = (args && args.flowType) || 'Business Process Flow'
+const complexity = (args && args.complexity) || 'medium(6-10)'
+const decisionPoints = (args && args.decisionPoints) || 'few(1-2)'
+const outputFile = (args && args.outputFile) || '_byan-output/excalidraw-diagrams/flowchart.excalidraw'
+const theme = (args && args.theme) || null
+
+const ELEMENTS_SCHEMA = {
+  type: 'object',
+  required: ['shapeCount', 'arrowCount', 'hasStart', 'hasEnd'],
+  properties: {
+    shapeCount: { type: 'number', description: 'number of labelled shapes built (circles/rectangles/diamonds)' },
+    arrowCount: { type: 'number', description: 'number of bound arrows built' },
+    diamondCount: { type: 'number', description: 'number of decision diamonds (should match decisionPoints)' },
+    hasStart: { type: 'boolean', description: 'true if a start circle with a label exists' },
+    hasEnd: { type: 'boolean', description: 'true if an end circle with a label exists' },
+    notes: { type: 'string' },
+  },
+}
+
+const JSON_SCHEMA = {
+  type: 'object',
+  required: ['valid'],
+  properties: {
+    valid: { type: 'boolean', description: 'true ONLY if `node -e JSON.parse(...)` on the saved file exits 0' },
+    error: { type: 'string', description: 'the parser error message + position when invalid' },
+  },
+}
+
+const CHECKLIST_SCHEMA = {
+  type: 'object',
+  required: ['pass', 'failedItems'],
+  properties: {
+    pass: { type: 'boolean', description: 'true if every applicable checklist item is satisfied' },
+    failedItems: { type: 'array', items: { type: 'string' }, description: 'checklist items that failed, verbatim' },
+    summary: { type: 'string' },
+  },
+}
+
+const SRC = '_byan/workflow/simple/excalidraw-diagrams/create-flowchart'
+const SHARED = '_byan/workflow/simple/excalidraw-diagrams/_shared'
+
+// === STEP 0 + 1 (CONTEXT) ===================================================
+// Source step 0 (Contextual Analysis) + step 1 (Gather Requirements) are the
+// elicitation gate; here we just restate the locked requirements that the skill
+// already collected, so every downstream leaf shares one understanding.
+phase('CONTEXT')
+const context = await agent(
+  `You are the BYAN create-flowchart workflow. Restate the LOCKED flowchart requirements as a short brief.\n` +
+    `flowType=${JSON.stringify(flowType)} complexity=${JSON.stringify(complexity)} ` +
+    `decisionPoints=${JSON.stringify(decisionPoints)} outputFile=${JSON.stringify(outputFile)} ` +
+    `theme=${theme ? 'provided' : 'none (will default to Professional Blue palette)'}.\n` +
+    `Do NOT ask questions — those were answered at the human gate. Just confirm the understanding in 2-3 lines.`,
+  { label: 'context-restate', phase: 'CONTEXT' }
+)
+
+// === STEP 4 (PLAN) ==========================================================
+phase('PLAN')
+const plan = await agent(
+  `Mirror create-flowchart step 4 (Plan Flowchart Layout). Brief: ${context}\n` +
+    `Enumerate the concrete nodes: ONE start circle, the process rectangles, exactly the decision diamonds implied ` +
+    `by decisionPoints=${JSON.stringify(decisionPoints)}, and ONE end circle. List the directed edges (including the ` +
+    `yes/no branches off each diamond). Keep total elements under 50 (checklist: Composition). ` +
+    `Output the ordered node list and the edge list — this is the structure the user approved at the gate.`,
+  { label: 'plan-layout', phase: 'PLAN' }
+)
+
+// === STEP 5 (RESOURCES) =====================================================
+phase('RESOURCES')
+const resources = await agent(
+  `Mirror create-flowchart step 5 (Load Template and Resources). Read these real files:\n` +
+    `- template: ${SHARED}/excalidraw-templates.yaml  -> extract the \`flowchart\` section\n` +
+    `- library:  ${SHARED}/excalidraw-library.json\n` +
+    `- helpers:  _byan/connaissance/excalidraw/excalidraw-helpers.md  (element-creation guidelines)\n` +
+    `- json-validation guide: _byan/connaissance/excalidraw/validate-json-instructions.md\n` +
+    `Merge the theme colors (${theme ? JSON.stringify(theme) : 'Professional Blue default: fill #e3f2fd, accent #1976d2, decision #fff3e0, text #1e1e1e'}) ` +
+    `onto the template. Report which template fields the flowchart will use and the resolved color palette. ` +
+    `If a file is missing, say so explicitly — do not invent its contents.`,
+  { label: 'load-resources', phase: 'RESOURCES' }
+)
+
+// === STEP 6 (BUILD) =========================================================
+phase('BUILD')
+const elements = await agent(
+  `Mirror create-flowchart step 6 (Build Flowchart Elements), following the helpers guidelines from RESOURCES.\n` +
+    `Plan: ${plan}\nResolved resources/palette: ${resources}\n` +
+    `Build ONE section at a time, in this order: start circle -> process rectangles -> decision diamonds -> end circle -> arrows.\n` +
+    `Per shape-with-label: unique shape-id/text-id/group-id; shape and its text share the SAME groupIds; ` +
+    `text width = round((text.length * fontSize * 0.6) + 20) to nearest 10; text has containerId=shape-id, ` +
+    `textAlign=center, verticalAlign=middle; add boundElements on the shape referencing the text.\n` +
+    `Per arrow: startBinding/endBinding with gap=10 to source/target shape ids; straight for forward flow, ` +
+    `elbow (with intermediate points) for upward/backward/complex routing; update boundElements on BOTH endpoints.\n` +
+    `Alignment: snap every x,y to a 20px grid; same x for vertical flow; 60px spacing between shapes.\n` +
+    `Produce the in-memory Excalidraw elements array (do not write the file yet) and report the counts.`,
+  { label: 'build-elements', phase: 'BUILD', schema: ELEMENTS_SCHEMA }
+)
+
+// === STEP 7 (SAVE) ==========================================================
+phase('SAVE')
+const saved = await agent(
+  `Mirror create-flowchart step 7 (Optimize and Save). Built elements: ${JSON.stringify(elements)}.\n` +
+    `Strip any element with isDeleted:true and any unused/orphan element. Wrap the array in a valid ` +
+    `Excalidraw document ({ type:"excalidraw", version:2, source, elements, appState, files }). ` +
+    `Write the file to ${JSON.stringify(outputFile)} (creating parent dirs as needed). ` +
+    `Confirm the byte path written and the final element count (must stay under 50).`,
+  { label: 'optimize-save', phase: 'SAVE' }
+)
+
+// === STEP 8 (VALIDATE_JSON) — bounded fix/re-validate loop ==================
+phase('VALIDATE_JSON')
+let fixCycles = 0
+let jsonRes = { valid: false, error: 'not yet validated' }
+let jsonGuard = { done: false, abort: false, reason: 'init' }
+while (true) {
+  fixCycles += 1
+  jsonRes = await agent(
+    `Mirror create-flowchart step 8 (Validate JSON Syntax), attempt ${fixCycles}. Save context: ${saved}\n` +
+      `CRITICAL: NEVER delete the file if validation fails — always FIX it.\n` +
+      `Run exactly: node -e "JSON.parse(require('fs').readFileSync('${outputFile}', 'utf8')); console.log('valid')"\n` +
+      (fixCycles > 1
+        ? `Previous error: ${jsonRes.error || 'unknown'}. Open the file at the error position, fix the missing comma/bracket/quote, save, then re-run the same command.\n`
+        : ``) +
+      `Set valid=true ONLY if that node command exits 0; otherwise valid=false and copy the parser error + position into \`error\`.`,
+    { label: `validate-json-${fixCycles}`, phase: 'VALIDATE_JSON', schema: JSON_SCHEMA }
+  )
+  jsonGuard = jsonFixGuard({ cycles: fixCycles, valid: Boolean(jsonRes && jsonRes.valid) })
+  log(`json-validate attempt ${fixCycles}: valid=${Boolean(jsonRes && jsonRes.valid)} -> ${jsonGuard.reason}`)
+  if (jsonGuard.done) break
+}
+
+// === STEP 9 (VALIDATE_CONTENT) ==============================================
+phase('VALIDATE_CONTENT')
+let checklist = { pass: false, failedItems: ['skipped — JSON never validated'], summary: 'skipped' }
+if (jsonRes.valid) {
+  checklist = await agent(
+    `Mirror create-flowchart step 9 (Validate Content). Validate the saved file ${JSON.stringify(outputFile)} ` +
+      `against the checklist at ${SRC}/checklist.md (Element Structure, Layout/Alignment, Connections, ` +
+      `Theme/Styling, Composition, Output Quality, Functional Requirements). ` +
+      `Read the checklist file, evaluate EACH applicable item against the actual file content, and report pass/fail per item.`,
+    { label: 'validate-content', phase: 'VALIDATE_CONTENT', schema: CHECKLIST_SCHEMA }
+  )
+}
+
+// === VERDICT — DATA ONLY ====================================================
+// The orchestrating skill presents this at the human gate (step 8 "Open to
+// view?" / step 3 theme-approval are human decisions) and records FD/strict
+// state via MCP. The script writes only the .excalidraw artifact, never state.
+phase('VERDICT')
+const jsonValid = Boolean(jsonRes && jsonRes.valid)
+const contentPass = Boolean(checklist && checklist.pass)
+return {
+  workflow: 'create-excalidraw-flowchart',
+  outputFile,
+  requirements: { flowType, complexity, decisionPoints, themedFromArgs: Boolean(theme) },
+  elements: {
+    shapeCount: (elements && elements.shapeCount) || 0,
+    arrowCount: (elements && elements.arrowCount) || 0,
+    diamondCount: (elements && elements.diamondCount) || 0,
+    hasStart: Boolean(elements && elements.hasStart),
+    hasEnd: Boolean(elements && elements.hasEnd),
+  },
+  jsonValid,
+  jsonFixCycles: fixCycles,
+  maxFixCycles: MAX_FIX_CYCLES,
+  jsonAbort: jsonGuard.abort,
+  contentValidationPass: contentPass,
+  failedChecklistItems: (checklist && checklist.failedItems) || [],
+  status: jsonValid && contentPass ? 'ready-to-open' : jsonGuard.abort ? 'aborted-invalid-json' : 'needs-attention',
+  summary:
+    jsonValid && contentPass
+      ? `Flowchart written to ${outputFile}; JSON valid and checklist passed.`
+      : `Flowchart at ${outputFile} needs attention: jsonValid=${jsonValid}, contentPass=${contentPass}.`,
+  needsHumanGate: true,
+}