create-byan-agent 2.19.2 → 2.20.1

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

@@ -0,0 +1,192 @@
+export const meta = {
+  name: 'create-excalidraw-wireframe',
+  description: 'Native port of the BYAN create-excalidraw-wireframe workflow: plan a website/app wireframe, load Excalidraw resources, build elements per screen at the requested fidelity, optimize and save the .excalidraw file, then validate JSON syntax (bounded fix loop) and content against the checklist. Returns a structured verdict; the elicitation steps (type, requirements, theme) stay at the human gate.',
+  phases: [
+    { title: 'CONTEXT', detail: 'step 0 - extract type, fidelity, screen count, device, save location from the request' },
+    { title: 'PLAN', detail: 'step 5 - list screens, map navigation flow, identify key UI elements' },
+    { title: 'LOAD', detail: 'step 6 - load templates(wireframe), library, theme.json, helpers' },
+    { title: 'BUILD', detail: 'step 7 - build wireframe elements per screen in the prescribed build order at the chosen fidelity' },
+    { title: 'SAVE', detail: 'step 8 - strip unused/isDeleted elements and save to the output file' },
+    { title: 'VALIDATE_JSON', detail: 'step 9 - JSON.parse the file; on failure fix syntax and re-check (bounded loop)' },
+    { title: 'VALIDATE_CONTENT', detail: 'step 10 - validate against checklist.md' },
+    { title: 'VERDICT', detail: 'return a structured verdict to the orchestrating skill' },
+  ],
+}
+
+// ---------------------------------------------------------------------------
+// FD / STRICT STATE CONTRACT  (re-asserted inline — enforcement-bridge).
+//
+// 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 (a fixed timestamp/id is
+//     passed in via args so resume stays deterministic).
+//   - 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 owns the four elicit="true" steps (1: wireframe type,
+//     2: requirements, 3: check theme, 4: create theme) — those are human
+//     decisions and are intentionally kept OUT of this autonomous engine.
+// The .excalidraw FILE is the workflow's product, written by the SAVE leaf —
+// that is the artifact, not BYAN platform state.
+// ---------------------------------------------------------------------------
+
+// Source paths (workflow.yaml) — passed to the agents so they read the REAL
+// resources rather than inventing schema/colors.
+const SRC = {
+  helpers: '_byan/connaissance/excalidraw/excalidraw-helpers.md',
+  jsonValidation: '_byan/connaissance/excalidraw/validate-json-instructions.md',
+  templates: '_byan/workflow/simple/excalidraw-diagrams/_shared/excalidraw-templates.yaml',
+  library: '_byan/workflow/simple/excalidraw-diagrams/_shared/excalidraw-library.json',
+  checklist: '_byan/workflow/simple/excalidraw-diagrams/create-wireframe/checklist.md',
+}
+
+// Inputs come from the human-gated elicitation steps (1-4), threaded in via args.
+// Defaults keep the engine runnable; the skill overrides them at the gate.
+const wireframeType = (args && args.wireframeType) || 'Web App (Responsive)'
+const fidelity = (args && args.fidelity) || 'Medium'
+const screenCount = (args && args.screenCount) || 'Few (2-3)'
+const device = (args && args.device) || 'standard responsive dimensions'
+const theme = (args && args.theme) || 'Classic Wireframe (white bg / light-gray container / gray border / dark-gray text)'
+// timestamp/id MUST be supplied (no clock/RNG in the sandbox).
+const timestamp = (args && args.timestamp) || 'TIMESTAMP'
+const outputFile = (args && args.outputFile) || `_byan-output/excalidraw-diagrams/wireframe-${timestamp}.excalidraw`
+
+// JSON-validation convergence guard (step 9). Mirrors the prose rule
+// "Repeat until validation passes" with a real integer cap so the model
+// cannot loop forever. NEVER delete the file on failure — always fix syntax.
+const MAX_FIX_PASSES = 3
+
+const VALIDATE_JSON_SCHEMA = {
+  type: 'object',
+  required: ['valid'],
+  properties: {
+    valid: { type: 'boolean', description: 'true ONLY if JSON.parse on the saved file succeeded' },
+    error: { type: 'string', description: 'the parser error and position when not valid' },
+    fixed: { type: 'boolean', description: 'true if a syntax fix was applied this pass' },
+  },
+}
+
+const CHECKLIST_SCHEMA = {
+  type: 'object',
+  required: ['pass', 'failedItems'],
+  properties: {
+    pass: { type: 'boolean', description: 'true only if every checklist item is satisfied' },
+    failedItems: { type: 'array', items: { type: 'string' }, description: 'checklist items not satisfied' },
+    notes: { type: 'string' },
+  },
+}
+
+// --- STEP 0: Contextual Analysis -------------------------------------------
+phase('CONTEXT')
+const context = await agent(
+  `You are create-excalidraw-wireframe (step 0, Contextual Analysis).\n` +
+    `Locked inputs from the human gate: type=${JSON.stringify(wireframeType)}, ` +
+    `fidelity=${JSON.stringify(fidelity)}, screenCount=${JSON.stringify(screenCount)}, ` +
+    `device=${JSON.stringify(device)}, theme=${JSON.stringify(theme)}, output=${JSON.stringify(outputFile)}.\n` +
+    `Restate these requirements cleanly and flag any that are still ambiguous (do NOT ask the user — ` +
+    `this engine runs headless; surface ambiguity as a note for the gate).`,
+  { label: 'context', phase: 'CONTEXT' }
+)
+
+// --- STEP 5: Plan Wireframe Structure --------------------------------------
+phase('PLAN')
+const plan = await agent(
+  `Step 5 (Plan Wireframe Structure). Context: ${context}\n` +
+    `List every screen and its purpose, map the navigation flow between screens, and identify the key UI ` +
+    `elements per screen. Honor screenCount=${JSON.stringify(screenCount)} and device=${JSON.stringify(device)}. ` +
+    `Output the planned structure as a clear screen-by-screen outline.`,
+  { label: 'plan', phase: 'PLAN' }
+)
+
+// --- STEP 6: Load Resources ------------------------------------------------
+phase('LOAD')
+const resources = await agent(
+  `Step 6 (Load Resources). Read these REAL files and extract what is needed:\n` +
+    `- templates: ${SRC.templates} (extract the \`wireframe\` section)\n` +
+    `- library: ${SRC.library}\n` +
+    `- helpers: ${SRC.helpers} (the authoritative element-creation rules)\n` +
+    `- the chosen theme: ${JSON.stringify(theme)} (use a theme.json if one exists).\n` +
+    `Summarize the wireframe template primitives, the relevant library elements, the theme color tokens, ` +
+    `and the element-creation constraints from helpers (grid 20px, containerId on text, grouping).`,
+  { label: 'load-resources', phase: 'LOAD' }
+)
+
+// --- STEP 7: Build Wireframe Elements --------------------------------------
+phase('BUILD')
+const build = await agent(
+  `Step 7 (Build Wireframe Elements). Follow ${SRC.helpers} strictly for element creation.\n` +
+    `Plan: ${plan}\nResources: ${resources}\n` +
+    `For EACH screen create: container/frame, header section, content areas, navigation elements, ` +
+    `interactive elements (buttons, inputs), labels and annotations.\n` +
+    `Respect this BUILD ORDER: (1) screen containers, (2) layout sections header/content/footer, ` +
+    `(3) navigation elements, (4) content blocks, (5) interactive elements, (6) labels/annotations, ` +
+    `(7) flow indicators if multi-screen.\n` +
+    `Apply fidelity=${JSON.stringify(fidelity)} — Low: basic shapes, minimal detail, placeholder text; ` +
+    `Medium: more defined elements, some styling, representative content; ` +
+    `High: detailed elements, realistic sizing, actual content examples.\n` +
+    `Produce the full Excalidraw element set (valid scene JSON) for all screens.`,
+  { label: 'build', phase: 'BUILD' }
+)
+
+// --- STEP 8: Optimize and Save ---------------------------------------------
+phase('SAVE')
+const saved = await agent(
+  `Step 8 (Optimize and Save). Built scene: ${build}\n` +
+    `Strip unused elements and any element with isDeleted:true. Then save the cleaned Excalidraw scene ` +
+    `to ${JSON.stringify(outputFile)} (create parent directories as needed). Report the saved path.`,
+  { label: 'save', phase: 'SAVE' }
+)
+
+// --- STEP 9: Validate JSON Syntax (bounded fix loop) -----------------------
+phase('VALIDATE_JSON')
+let jsonPass = 0
+let jsonResult = { valid: false, error: 'not started' }
+while (true) {
+  jsonPass += 1
+  jsonResult = await agent(
+    `Step 9 (Validate JSON Syntax), pass ${jsonPass}/${MAX_FIX_PASSES}. Saved file: ${saved}\n` +
+      `Run: node -e "JSON.parse(require('fs').readFileSync('${outputFile}', 'utf8')); console.log('Valid JSON')".\n` +
+      `Follow ${SRC.jsonValidation} for the validation procedure. ` +
+      `CRITICAL: NEVER delete the file if validation fails — read the parser error (it shows the syntax ` +
+      `error and position), open the file at that location, fix the missing comma/bracket/quote, save, ` +
+      `and report. Set valid=true only when JSON.parse succeeds.`,
+    { label: `validate-json-${jsonPass}`, phase: 'VALIDATE_JSON', schema: VALIDATE_JSON_SCHEMA }
+  )
+  log(`json pass ${jsonPass}: valid=${Boolean(jsonResult && jsonResult.valid)}`)
+  if (jsonResult && jsonResult.valid) break
+  if (jsonPass >= MAX_FIX_PASSES) break
+}
+
+// --- STEP 10: Validate Content (against checklist) -------------------------
+phase('VALIDATE_CONTENT')
+const checklist = await agent(
+  `Step 10 (Validate Content). Validate the saved wireframe ${JSON.stringify(outputFile)} against the ` +
+    `REAL checklist at ${SRC.checklist}. Check layout structure (device-appropriate dimensions, 20px grid ` +
+    `alignment, consistent spacing, header/content/footer hierarchy), UI elements (interactive elements ` +
+    `marked, controls sized, readable labels, navigation indicated), fidelity match (${JSON.stringify(fidelity)}), ` +
+    `annotations (interactions, flow indicators if multi-screen, notes, element purposes), and technical ` +
+    `quality (grouping, text containerId, grid snapping, no isDeleted:true, valid JSON, correct save path). ` +
+    `Report pass=true only if every item is satisfied; otherwise list the failed items.`,
+  { label: 'validate-content', phase: 'VALIDATE_CONTENT', schema: CHECKLIST_SCHEMA }
+)
+
+// --- VERDICT: data only, gate is owned by the orchestrating skill ----------
+phase('VERDICT')
+const jsonValid = Boolean(jsonResult && jsonResult.valid)
+const contentPass = Boolean(checklist && checklist.pass)
+return {
+  workflow: 'create-excalidraw-wireframe',
+  summary: `Wireframe (${wireframeType}, ${fidelity} fidelity, ${screenCount}) built and saved to ${outputFile}.`,
+  inputs: { wireframeType, fidelity, screenCount, device, theme, outputFile },
+  steps: 7,
+  outputFile,
+  jsonValid,
+  jsonFixPasses: jsonPass,
+  maxJsonFixPasses: MAX_FIX_PASSES,
+  contentPass,
+  failedChecklistItems: (checklist && checklist.failedItems) || [],
+  status: jsonValid && contentPass ? 'ready-for-review' : jsonValid ? 'content-gaps' : 'invalid-json',
+  needsHumanGate: true,
+}

package/install/templates/.claude/workflows/create-story.js

@@ -0,0 +1,216 @@
+export const meta = {
+  name: 'create-story',
+  description: 'Native port of the BYAN create-story workflow: select the next backlog story, exhaustively analyze epics + previous story + git + architecture, web-research latest tech, write the ULTIMATE ready-for-dev story file from the template, then return a structured verdict for the orchestrating skill to update sprint-status and present at the human gate.',
+  phases: [
+    { title: 'TARGET', detail: 'determine the target story (auto-discover first backlog from sprint-status, or use the provided story key)' },
+    { title: 'ARTIFACTS', detail: 'load + exhaustively analyze epics, previous story learnings, and git history' },
+    { title: 'ARCHITECTURE', detail: 'extract architecture guardrails the developer MUST follow' },
+    { title: 'RESEARCH', detail: 'web-research latest stable versions / breaking changes for the relevant tech' },
+    { title: 'WRITE', detail: 'create the comprehensive story file from template.md and set Status: ready-for-dev' },
+    { title: 'FINALIZE', detail: 'validate against the checklist and return a verdict (sprint-status update + report happen at the gate)' },
+  ],
+}
+
+// ---------------------------------------------------------------------------
+// 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, 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 (Date/RNG break
+//     resume); any date/id is passed in via args.
+//   - returns DATA only. The orchestrating skill is the human-gated conductor:
+//     IT updates sprint-status.yaml (source step 6) and records FD/strict state
+//     via the byan_fd_* / byan_strict_* MCP tools AT the gate. Source step 1's
+//     HALT/ask branches (no sprint file, no backlog, done/invalid epic) are
+//     human gates -> surfaced as a verdict, never decided inside the script.
+// The story FILE (the {{story_key}}.md product) is the workflow's artifact,
+// written by the WRITE leaf — that is the deliverable, not BYAN platform state.
+// ---------------------------------------------------------------------------
+
+// Inputs are passed in (no fs, no clock, no RNG in the sandbox).
+// storyKey: explicit "epic-story-title" the user provided (skips auto-discover).
+// date: caller-supplied date string for the story header (system-generated upstream).
+const storyKey = (args && args.storyKey) || null
+const date = (args && args.date) || 'unspecified'
+const storyDir = (args && args.storyDir) || '{implementation_artifacts}'
+
+// Verdict shape for the TARGET step: either a story is resolved, or we hit one
+// of source step 1's human-gate conditions (HALT/ask) that the script must NOT
+// resolve on its own.
+const TARGET_SCHEMA = {
+  type: 'object',
+  required: ['resolved'],
+  properties: {
+    resolved: { type: 'boolean', description: 'true if a concrete target story key was determined' },
+    epicNum: { type: 'string' },
+    storyNum: { type: 'string' },
+    storyKey: { type: 'string', description: 'e.g. 1-2-user-authentication' },
+    storyId: { type: 'string', description: 'e.g. 1.2' },
+    storyTitle: { type: 'string' },
+    isFirstStoryInEpic: { type: 'boolean', description: 'true if matches {epicNum}-1-*; epic should be flagged in-progress at the gate' },
+    gate: {
+      type: 'string',
+      description: 'human-gate condition when resolved=false: no-sprint-status | no-backlog | epic-done | invalid-epic-status | none',
+    },
+    gateMessage: { type: 'string', description: 'message to surface to the human when resolved=false' },
+  },
+}
+
+// Verdict shape for the final FINALIZE step.
+const FINAL_SCHEMA = {
+  type: 'object',
+  required: ['storyFileWritten', 'status', 'checklistVerdict'],
+  properties: {
+    storyFileWritten: { type: 'boolean' },
+    storyFilePath: { type: 'string' },
+    status: { type: 'string', description: "the Status set in the story file; must be 'ready-for-dev' on success" },
+    checklistVerdict: { type: 'string', enum: ['pass', 'gaps'], description: 'result of validating the story against checklist.md' },
+    criticalIssues: { type: 'array', items: { type: 'string' }, description: 'checklist critical misses (must-fix)' },
+    enhancements: { type: 'array', items: { type: 'string' } },
+    openQuestions: { type: 'array', items: { type: 'string' }, description: 'questions saved for the end (source: SAVE QUESTIONS rule)' },
+  },
+}
+
+// === STEP 1 — Determine target story =======================================
+// Source: instructions.xml step n="1". Auto-discover the FIRST backlog story
+// from sprint-status.yaml (read top-to-bottom, preserve order), OR honour an
+// explicitly provided story key. The HALT/ask branches (missing sprint file,
+// no backlog story, epic done, invalid epic status) are HUMAN gates: the agent
+// reports them via resolved=false + gate, it does NOT pick or HALT autonomously.
+phase('TARGET')
+const target = await agent(
+  `You are create-story (BYAN). Goal: determine the target story.\n` +
+    `Read the REAL source: _byan/workflow/simple/4-implementation/create-story/workflow.yaml and instructions.xml (step 1).\n` +
+    (storyKey
+      ? `The user provided a story key: ${JSON.stringify(storyKey)}. Parse it into epicNum, storyNum, storyTitle (format "epic-story-title", e.g. "1-2-user-auth"). Set storyId = "{epicNum}.{storyNum}", storyKey, resolved=true, gate="none".`
+      : `No story key was provided. Read the COMPLETE sprint-status.yaml (variable {implementation_artifacts}/sprint-status.yaml) from start to end, preserving order. Parse development_status fully. Find the FIRST story key (top-to-bottom) matching number-number-name, NOT an epic-X or epic-X-retrospective key, whose status equals "backlog". Extract epicNum (before first dash), storyNum (after first dash), storyTitle (remainder); set storyId="{epicNum}.{storyNum}".\n` +
+        `Then detect the HUMAN-GATE conditions and report them WITHOUT deciding:\n` +
+        `  - sprint-status.yaml missing -> resolved=false, gate="no-sprint-status".\n` +
+        `  - no backlog story found -> resolved=false, gate="no-backlog".\n` +
+        `  - if this is the first story in the epic ({epicNum}-1-*): check epic-{epicNum} status. If "done" -> resolved=false, gate="epic-done". If not one of backlog/contexted/in-progress/done -> resolved=false, gate="invalid-epic-status". Otherwise set isFirstStoryInEpic=true (the epic should be flagged in-progress at the gate) and resolved=true.\n` +
+        `  - otherwise resolved=true, gate="none".`) +
+    `\nDo NOT write any file in this step. Only resolve / report the target.`,
+  { label: 'determine-target', phase: 'TARGET', schema: TARGET_SCHEMA }
+)
+log(`target: resolved=${target.resolved} key=${target.storyKey || '(none)'} gate=${target.gate || 'n/a'}`)
+
+// If a human gate blocks selection, stop the autonomous run and return the
+// gate to the orchestrating skill. The script never HALTs or asks the user.
+if (!target.resolved) {
+  return {
+    workflow: 'create-story',
+    summary: `Target story could not be resolved autonomously — human gate: ${target.gate}.`,
+    steps: 1,
+    needsHumanGate: true,
+    gate: target.gate,
+    gateMessage: target.gateMessage || '',
+    target,
+  }
+}
+
+const resolvedKey = target.storyKey
+const storyFilePath = `${storyDir}/${resolvedKey}.md`
+
+// === STEP 2 — Load and analyze core artifacts ==============================
+// Source: step n="2". Exhaustive (NOT lazy) analysis of epics for THIS story,
+// previous-story intelligence (if storyNum > 1), and git history for recent
+// work patterns. This is where future developer mistakes are prevented.
+phase('ARTIFACTS')
+const artifacts = await agent(
+  `create-story step 2 — EXHAUSTIVE artifact analysis for story ${JSON.stringify(resolvedKey)} (id ${target.storyId}). Do NOT skim.\n` +
+    `Run discover_inputs: load epics ({planning_artifacts}/*epic*.md), and fall back to prd / architecture / ux / project-context only as needed.\n` +
+    `EPIC ANALYSIS: from epics, extract Epic ${target.epicNum} objectives + business value, ALL stories in the epic (cross-story context), our story's user-story statement + BDD acceptance criteria + technical requirements + dependencies + source hints.\n` +
+    `STORY FOUNDATION: As-a / I-want / so-that, detailed acceptance criteria, story-specific technical requirements, success criteria.\n` +
+    `PREVIOUS STORY INTELLIGENCE: if storyNum (${target.storyNum}) > 1, load the previous story file ${storyDir}/${target.epicNum}-{previous_story_num}-*.md and extract dev notes, review feedback, files created/modified + their patterns, testing approaches that worked/failed, problems + solutions, code patterns established.\n` +
+    `GIT INTELLIGENCE: if a previous story exists AND a git repo is detected, read the last 5 commit titles; analyze recent commits for files touched, conventions, dependency changes, architecture decisions, testing approaches; extract actionable insights for this story.\n` +
+    `Return a tight, structured analysis (no fluff). Save any clarifying questions for the END (do not ask now).`,
+  { label: 'analyze-artifacts', phase: 'ARTIFACTS' }
+)
+
+// === STEP 3 — Architecture analysis for developer guardrails ===============
+// Source: step n="3". Pull every architecture constraint the developer MUST
+// follow (stack/versions, structure, API, DB, security, performance, testing,
+// deployment, integration); flag decisions that override previous patterns.
+phase('ARCHITECTURE')
+const architecture = await agent(
+  `create-story step 3 — ARCHITECTURE guardrails for story ${JSON.stringify(resolvedKey)}.\n` +
+    `Artifact analysis so far: ${artifacts}\n` +
+    `Load architecture: complete file if single, or the index + all shards if sharded ({planning_artifacts}/*architecture*.md or */*.md).\n` +
+    `For each section, decide relevance to THIS story and extract what the developer MUST follow: Technical Stack (languages/frameworks/libraries WITH versions); Code Structure (folders, naming, file patterns); API Patterns (service structure, endpoints, data contracts); Database Schemas (tables/relationships/constraints relevant to the story); Security Requirements (auth/authz); Performance Requirements (caching, optimization); Testing Standards (frameworks, coverage, patterns); Deployment Patterns; Integration Patterns (external services, data flows).\n` +
+    `Explicitly identify any architectural decision that OVERRIDES a previous pattern. Return a tight list of binding constraints.`,
+  { label: 'analyze-architecture', phase: 'ARCHITECTURE' }
+)
+
+// === STEP 4 — Web research for latest technical specifics ==================
+// Source: step n="4". For each critical library/framework, research latest
+// stable version + breaking changes + security/perf notes + best practices,
+// so the story never carries outdated implementation guidance.
+phase('RESEARCH')
+const research = await agent(
+  `create-story step 4 — LATEST-TECH web research for story ${JSON.stringify(resolvedKey)}.\n` +
+    `From the architecture guardrails: ${architecture}\n` +
+    `Identify the specific libraries / APIs / frameworks this story depends on. For each critical one, research: latest stable version + key breaking changes; security vulnerabilities/updates; performance improvements/deprecations; best practices for the current version; migration considerations if upgrading.\n` +
+    `Return ONLY the critical, story-relevant facts the developer needs (specific versions and WHY, endpoints with params/auth, recent security patches, perf techniques). If no external lookup is warranted, say so explicitly rather than padding.`,
+  { label: 'web-research', phase: 'RESEARCH' }
+)
+
+// === STEP 5 — Create comprehensive story file ==============================
+// Source: step n="5". Initialize from template.md and write the full story:
+// header, requirements, the developer_context section (MOST IMPORTANT), tech
+// requirements, architecture compliance, library/framework reqs, file-structure
+// reqs, testing reqs, previous-story intelligence, git summary, latest tech,
+// project-context reference, completion status; set Status: ready-for-dev.
+phase('WRITE')
+const written = await agent(
+  `create-story step 5 — WRITE the ULTIMATE story file at ${storyFilePath} (story ${target.storyId}, date ${date}).\n` +
+    `Initialize from the template: _byan/workflow/simple/4-implementation/create-story/template.md (keep its section order).\n` +
+    `Fill EVERY relevant section from the analyses below — this single file is ALL the dev agent will have, so make flawless implementation inevitable:\n` +
+    `  story_header (epic_num/story_num/title, Status), story_requirements (As-a/I-want/so-that + Acceptance Criteria + Tasks/Subtasks with AC refs),\n` +
+    `  developer_context_section (MOST IMPORTANT — anti-reinvention, exact file locations, reuse opportunities),\n` +
+    `  technical_requirements, architecture_compliance, library_framework_requirements, file_structure_requirements, testing_requirements,\n` +
+    `  previous_story_intelligence (only if available), git_intelligence_summary (only if git analysis ran), latest_tech_information (only if research produced facts),\n` +
+    `  project_context_reference, story_completion_status.\n` +
+    `EPICS/STORY ANALYSIS:\n${artifacts}\nARCHITECTURE GUARDRAILS:\n${architecture}\nLATEST-TECH:\n${research}\n` +
+    `Cite technical details with source paths/sections, e.g. [Source: docs/<file>.md#Section]. Set Status to "ready-for-dev" and add the completion note "Ultimate context engine analysis completed - comprehensive developer guide created". Write ONLY the story file. Report the path written and the Status set.`,
+  { label: 'write-story', phase: 'WRITE' }
+)
+log(`write: ${typeof written === 'string' ? written.slice(0, 120) : 'done'}`)
+
+// === STEP 6 — Validate against checklist & finalize ========================
+// Source: step n="6". Validate the freshly written story against checklist.md
+// (the quality-competition reviewer) and report gaps. The unconditional save,
+// the sprint-status.yaml update (backlog -> ready-for-dev) and the user report
+// are the HUMAN-GATE side: the script returns a verdict; the skill applies
+// the sprint-status mutation and surfaces the report.
+phase('FINALIZE')
+const finalVerdict = await agent(
+  `create-story step 6 — VALIDATE the story at ${storyFilePath} against the checklist: _byan/workflow/simple/4-implementation/create-story/checklist.md.\n` +
+    `Re-analyze the source artifacts with a critical eye (the checklist is a fresh-context quality reviewer hunting for misses the writer left). Classify findings: critical issues (must-fix blockers), enhancements (should-add), and any open questions you saved for the end.\n` +
+    `Confirm the story file was written and its Status is exactly "ready-for-dev". Set checklistVerdict="pass" only if there are NO critical issues, otherwise "gaps". Do NOT modify sprint-status.yaml here — that mutation happens at the human gate.`,
+  { label: 'validate-checklist', phase: 'FINALIZE', schema: FINAL_SCHEMA }
+)
+log(`finalize: status=${finalVerdict.status} checklist=${finalVerdict.checklistVerdict}`)
+
+// Return DATA only. The orchestrating skill presents this at the human gate,
+// updates sprint-status.yaml (backlog -> ready-for-dev), optionally flags the
+// epic in-progress, and records FD/strict state via MCP.
+return {
+  workflow: 'create-story',
+  storyKey: resolvedKey,
+  storyId: target.storyId,
+  storyFilePath,
+  status: finalVerdict.status,
+  isFirstStoryInEpic: Boolean(target.isFirstStoryInEpic),
+  checklistVerdict: finalVerdict.checklistVerdict,
+  criticalIssues: finalVerdict.criticalIssues || [],
+  enhancements: finalVerdict.enhancements || [],
+  openQuestions: finalVerdict.openQuestions || [],
+  steps: 6,
+  summary: `Story ${resolvedKey} written to ${storyFilePath} as ready-for-dev (checklist: ${finalVerdict.checklistVerdict}).`,
+  needsHumanGate: true,
+  // Action the skill must apply at the gate (kept OUT of the script):
+  sprintStatusUpdate: { storyKey: resolvedKey, from: 'backlog', to: 'ready-for-dev' },
+}

package/install/templates/.claude/workflows/dev-story.js

@@ -0,0 +1,100 @@
+export const meta = {
+  name: 'dev-story',
+  description: 'Native port of the BYAN dev-story workflow: implement a story task-by-task via a red-green-refactor loop, run to green (or hard-abort at the 3-cycle convergence cap), and return a structured verdict for the orchestrating skill to present at the human gate.',
+  phases: [
+    { title: 'LOAD', detail: 'load the story + first incomplete task' },
+    { title: 'RGR', detail: 'red-green-refactor loop until green or the 3-cycle cap' },
+    { title: 'VERDICT', detail: 'return a structured verdict to the orchestrating skill' },
+  ],
+}
+
+// ---------------------------------------------------------------------------
+// FD / STRICT STATE CONTRACT  (re-asserted inline — enforcement-bridge F3).
+//
+// 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).
+//   - returns DATA only. The orchestrating skill (.claude/skills/
+//     byan-native-dev-story) is the human-gated conductor; IT records FD/strict
+//     state via the byan_fd_* / byan_strict_* MCP tools AT the gate.
+// The story FILE (Status, Tasks/Subtasks, Dev Agent Record, File List, Change
+// Log) is the workflow's product, written by the implement leaf — that is the
+// artifact, not BYAN platform state.
+// ---------------------------------------------------------------------------
+
+// Convergence guard — mirror of _byan/mcp/byan-mcp-server/lib/native-loop.js.
+// The sandbox forbids import, so the tiny guard is inlined verbatim; the lib
+// copy is the unit-tested reference (test/native-loop.test.js). Keep in sync.
+// This turns dev-story's prose rule ("3 consecutive failures -> HALT") into a
+// real JS counter the model cannot silently overrun.
+const MAX_CYCLES = 3
+function convergenceGuard({ cycles, green, maxCycles = MAX_CYCLES }) {
+  if (green) return { done: true, abort: false, reason: 'green' }
+  if (cycles >= maxCycles) return { done: true, abort: true, reason: `no convergence after ${maxCycles} cycles` }
+  return { done: false, abort: false, reason: 'continue' }
+}
+
+const VERIFY_SCHEMA = {
+  type: 'object',
+  required: ['green', 'blocking'],
+  properties: {
+    green: { type: 'boolean', description: 'true ONLY if the full test suite passes and the current task acceptance criteria are met' },
+    blocking: { type: 'array', items: { type: 'string' }, description: 'blocking issues when not green' },
+    summary: { type: 'string', description: 'one-line status' },
+  },
+}
+
+const story = (args && args.story) || 'next ready-for-dev story'
+
+phase('LOAD')
+const loaded = await agent(
+  `You are dev-story (BYAN dev agent). Target story: ${JSON.stringify(story)}.\n` +
+    `Read the COMPLETE story file. Parse Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, File List, Status. ` +
+    `Identify the FIRST incomplete task (unchecked [ ]). Report the story key and that task. ` +
+    `If no story is found or the file is inaccessible, say so explicitly (do not invent one).`,
+  { label: 'load-story', phase: 'LOAD' }
+)
+
+phase('RGR')
+// Red-green-refactor loop with a real convergence counter (max 3 cycles).
+let cycles = 0
+let last = { green: false, blocking: ['not started'] }
+let guard = { done: false, abort: false, reason: 'init' }
+while (true) {
+  cycles += 1
+  const impl = await agent(
+    `dev-story red-green-refactor, cycle ${cycles}, story ${JSON.stringify(story)}.\n` +
+      `Load context: ${loaded}\n` +
+      `On the first incomplete task: (RED) write FAILING tests first and confirm they fail; ` +
+      `(GREEN) implement the MINIMAL code to pass; (REFACTOR) improve structure while keeping tests green. ` +
+      `Modify ONLY the permitted story-file sections (Tasks/Subtasks checkboxes, Dev Agent Record, File List, Change Log, Status). ` +
+      `Do NOT mark a task [x] unless its tests actually pass. Then stop and report what you did.`,
+    { label: `rgr-cycle-${cycles}`, phase: 'RGR' }
+  )
+  last = await agent(
+    `Run the project's full test suite for story ${JSON.stringify(story)} (infer the test command from the repo). ` +
+      `Cycle ${cycles}. Implementation notes: ${impl}\n` +
+      `Set green=true ONLY if all tests pass with zero regressions AND the current task's acceptance criteria are met. ` +
+      `Otherwise green=false and list the blocking issues precisely.`,
+    { label: `verify-cycle-${cycles}`, phase: 'RGR', schema: VERIFY_SCHEMA }
+  )
+  guard = convergenceGuard({ cycles, green: Boolean(last && last.green) })
+  log(`cycle ${cycles}: green=${Boolean(last && last.green)} -> ${guard.reason}`)
+  if (guard.done) break
+}
+
+phase('VERDICT')
+// Return DATA only. The skill presents this at the human gate and records state.
+return {
+  workflow: 'dev-story',
+  story,
+  status: last.green ? 'review-ready' : guard.abort ? 'aborted-no-convergence' : 'in-progress',
+  green: Boolean(last.green),
+  cycles,
+  maxCycles: MAX_CYCLES,
+  blocking: (last && last.blocking) || [],
+  reason: guard.reason,
+  needsHumanGate: true,
+}