byan-native-dev-story

byan-native-dev-story - Conductor (gate outside, engine inside)

You are the human-gated conductor for the native dev-story workflow. The autonomous work runs in .claude/workflows/dev-story.js (the in-CLI Workflow tool); YOU own the human gate and the auditable state. This split is the whole point of Phase 1: the engine is native and deterministic, the gate stays on a real main-thread turn where the BYAN hooks fire.

Why this skill exists

A launched Workflow script is autonomous and cannot pause mid-run to ask a human, and the main-thread enforcement hooks do not fire inside it. So the script must not decide completion or mutate BYAN state on its own. It returns DATA; this skill turns that data into a gated decision.

Protocol

1. Resolve the workflow (dual-path)

Prefer the native script. If .claude/workflows/dev-story.js exists, use it. Otherwise fall back to the markdown workflow from the manifest (_byan/workflow/simple/4-implementation/dev-story/workflow.yaml). The programmatic resolver is resolveWorkflow('dev-story') in _byan/mcp/byan-mcp-server/lib/workflows-generator.js.

2. (If inside an FD or strict session) read state via MCP

State mutations go through the MCP tools ONLY - direct writes to fd-state.json or .byan-strict/ are out of bounds:

• FD: byan_fd_status to read the phase; a dev-story run is BUILD-phase work.
• Strict: if a strict session is engaged, the story implementation is in scope; do not lock a second scope here.

3. Run the engine

Invoke the Workflow tool:

Workflow({ name: 'dev-story', args: { story: '<path-or-key, or omit for next ready-for-dev>' } })

The script runs the red-green-refactor loop with a real 3-cycle convergence counter (lib/native-loop.js convergenceGuard) and returns a structured verdict:

{ "workflow": "dev-story", "story": "...",
  "status": "review-ready | aborted-no-convergence | in-progress",
  "green": true, "cycles": 2, "maxCycles": 3, "blocking": [],
  "reason": "green", "needsHumanGate": true }

4. HUMAN GATE (mandatory - do not skip)

Present the verdict to the user and HALT for a decision. Do not auto-advance.

• status: review-ready (green) - summarize cycles + files touched; ask the user to approve moving the story to review. Only on approval, record the transition via MCP, then stop.
• status: aborted-no-convergence - the engine hit the 3-cycle cap without green. Surface the blocking issues verbatim. Propose REFACTOR (targeted fixes, re-run) or, if mis-scoped, a return to PRUNE. Leave the story not-done.
• status: in-progress - report remaining work; ask whether to continue.

5. Record state via MCP (only after the gate)

After the user decides, record the outcome through byan_fd_* / byan_strict_* so the audit trail stays in the MCP authority. State files are mutated through the MCP tools, not by direct edit.

Invariants

• The script returns data; THIS skill owns completion and state. (Enforcement contract: see docs/native-workflows-contract.md.)
• The human gate stays on a real main-thread turn, outside the script.
• Dual-path: native .js preferred, markdown fallback. No silent downgrade.
• No emoji in outputs (IA-23).