create-byan-agent 2.19.2 → 2.20.0

package/install/templates/docs/native-workflows-contract.md

@@ -0,0 +1,84 @@
+# Native Workflows — Contract (Phase 1)
+
+> How BYAN workflows run on Claude Code's native Workflow tool, and the rules a
+> native workflow script must respect. Phase 1 of the native-workflow bridge.
+
+## The two execution models
+
+| | BYAN markdown/YAML workflow | Native (in-CLI Workflow tool) |
+|---|---|---|
+| Engine | the LLM interprets step files | a deterministic JS script |
+| Human gate | a menu/HALT per step | none in-run (autonomous once launched) |
+| Enforcement hooks | fire on the main-thread turn | do not fire inside the script |
+
+A launched Workflow script is autonomous and runs OUTSIDE the conversation turn.
+It cannot pause mid-run to ask a human, and the BYAN main-thread hooks
+(`fd-phase-guard`, `strict-scope-guard`, `strict-stop-guard`, `mantra-validate`)
+do not fire for work done inside it. That single fact drives the whole contract.
+
+## What is portable, and what is not
+
+Only workflows whose steps run WITHOUT a per-step human gate are portable. The
+read-based classification of the 45-workflow manifest gives three buckets
+(source of truth: `_byan/mcp/byan-mcp-server/lib/workflows-generator.js`):
+
+- **autonomous** (11) — `dev-story`, `create-story`, `qa-automate`, the 8
+  `testarch-*`. Run to completion with only error HALTs.
+- **pipeline** (9) — `sprint-planning`, `code-review`, `document-project`,
+  `check-implementation-readiness`, `quick-dev`, the 4 `create-excalidraw-*`.
+  Deterministic multi-stage, minimal interaction.
+- **gated** (25) — the `create-*` authoring flows, the CIS coaching workflows,
+  `party-mode`, the builders, etc. Their defining feature is a human menu per
+  step, so they stay LLM-interpreted markdown. They are out of scope for a
+  native port.
+
+The registry of portable workflows is generated into `.claude/workflows/INDEX.md`
+by `byan-build-workflows` (run: `node _byan/mcp/byan-mcp-server/bin/byan-build-workflows.js`).
+
+## Dual-path resolution
+
+`resolveWorkflow(name)` prefers the native script `.claude/workflows/<name>.js`
+when it exists, and otherwise falls back to the markdown workflow path from the
+manifest. This is the same Gen3-first dual-path idea used for agent stubs:
+adding a native script is additive, and removing it falls back cleanly.
+
+## The Hybrid rule — gate outside, engine inside
+
+The gated parts of a workflow stay in a skill on a real main-thread turn (where
+the hooks fire); only the autonomous work runs inside the native script.
+
+- The script returns DATA (a structured verdict). It does not decide completion.
+- The orchestrating skill (e.g. `byan-native-dev-story`) owns the human gate and
+  records FD/strict state via the MCP tools.
+
+## The state-coupling rule (enforced)
+
+A native workflow script must respect:
+
+1. It returns data; it does not mutate BYAN platform state on its own.
+2. FD and strict state are mutated only through the `byan_fd_*` / `byan_strict_*`
+   MCP tools. Importing or requiring `lib/fd-state.js` (or the `strict-mode` lib)
+   from a script is forbidden, and a direct write to `fd-state.json` /
+   `.byan-strict/` is out of bounds.
+3. The story file (or any workflow artifact) the script produces is fine to
+   write — that is the product, not platform state.
+
+This rule is enforced two ways, because the in-session hooks do not fire inside
+a script:
+
+- **`byan-lint-workflows`** (`node _byan/mcp/byan-mcp-server/bin/byan-lint-workflows.js`)
+  scans `.claude/workflows/*.js` and fails on a forbidden import/require.
+- **the pre-commit gate** (`.githooks/pre-commit`) runs that linter, so a
+  coupling violation blocks the commit. Bypass is `git commit --no-verify`
+  (emergency only).
+
+Because a script cannot rely on the hooks, it should also re-assert the contract
+inline (a comment block naming this file) so the next reader sees the rule.
+
+## Resume safety
+
+The Workflow runtime forbids wall-clock and RNG calls inside a script (they
+break runId resume). Timestamps and ids are passed in via `args`. Helper logic
+that needs testing lives in a lib module (e.g.
+`_byan/mcp/byan-mcp-server/lib/native-loop.js`) and is mirrored inline in the
+script, since the sandbox forbids `import` inside a script.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-byan-agent",
-  "version": "2.19.2",
-  "description": "BYAN v2.8 - Intelligent AI agent creator with ELO trust system + scientific fact-check + Hermes universal dispatcher + native Claude Code integration (hooks, skills, MCP server). Multi-platform (Copilot CLI, Claude Code, Codex). Merise Agile + TDD + 64 Mantras. ~54% LLM cost savings.",
+  "version": "2.20.0",
+  "description": "BYAN v2.8 - Intelligent AI agent creator with ELO trust system + scientific fact-check + Hermes universal dispatcher + native Claude Code integration (hooks, skills, MCP server). Multi-platform (Copilot CLI, Claude Code, Codex). Merise Agile + TDD + 71 Mantras. ~54% LLM cost savings.",
   "main": "src/index.js",
   "bin": {
     "create-byan-agent": "./install/bin/create-byan-agent-v2.js",

package/src/byan-v2/data/agent-scopes.json

@@ -0,0 +1,46 @@
+{
+  "version": "1.1.0",
+  "note": "Per-agent mantra scope map for domain-aware validation. resolveAgentScopes() precedence: explicit frontmatter mantra_scopes > agentScopes[name] > moduleScopes[module] > fallback [universal]. The 'universal' scope is force-unioned at every level so it is never dropped. v1.1 adds 'sdlc-ops' (release/deploy split from sdlc-code) and 'creative' (the CIS family). Edit this file to retune which mantra families a persona is scored against.",
+  "scopeNames": ["universal", "sdlc-process", "sdlc-code", "sdlc-ops", "sdlc-modeling", "sdlc-test", "creative"],
+  "moduleScopes": {
+    "bmm": ["universal", "sdlc-process", "sdlc-code", "sdlc-modeling", "sdlc-test"],
+    "cis": ["universal", "creative"],
+    "tea": ["universal", "sdlc-test", "sdlc-process"],
+    "bmb": ["universal", "sdlc-process", "sdlc-code", "sdlc-modeling", "sdlc-test"],
+    "core": ["universal", "sdlc-process"]
+  },
+  "agentScopes": {
+    "analyst": ["universal", "sdlc-process", "sdlc-modeling"],
+    "architect": ["universal", "sdlc-modeling", "sdlc-code", "sdlc-process"],
+    "dev": ["universal", "sdlc-code", "sdlc-test"],
+    "pm": ["universal", "sdlc-process"],
+    "sm": ["universal", "sdlc-process"],
+    "quinn": ["universal", "sdlc-test"],
+    "tech-writer": ["universal", "sdlc-code"],
+    "ux-designer": ["universal", "sdlc-process"],
+    "quick-flow-solo-dev": ["universal", "sdlc-code", "sdlc-test"],
+    "expert-merise-agile": ["universal", "sdlc-modeling", "sdlc-process"],
+    "tea": ["universal", "sdlc-test", "sdlc-process"],
+    "hermes": ["universal"],
+    "bmad-master": ["universal", "sdlc-process"],
+    "yanstaller": ["universal", "sdlc-code", "sdlc-ops"],
+    "fact-checker": ["universal"],
+    "byan": ["universal", "sdlc-process", "sdlc-code", "sdlc-modeling", "sdlc-test"],
+    "agent-builder": ["universal", "sdlc-process", "sdlc-code"],
+    "module-builder": ["universal", "sdlc-process", "sdlc-code"],
+    "workflow-builder": ["universal", "sdlc-process", "sdlc-code"],
+    "marc": ["universal", "sdlc-code", "sdlc-ops"],
+    "rachid": ["universal", "sdlc-code", "sdlc-ops"],
+    "carmack": ["universal", "sdlc-code"],
+    "patnote": ["universal", "sdlc-code", "sdlc-ops"],
+    "codex": ["universal", "sdlc-code", "sdlc-ops"],
+    "claude": ["universal", "sdlc-code", "sdlc-ops"],
+    "drawio": ["universal", "sdlc-modeling"],
+    "brainstorming-coach": ["universal", "creative"],
+    "creative-problem-solver": ["universal", "creative"],
+    "design-thinking-coach": ["universal", "creative"],
+    "innovation-strategist": ["universal", "creative"],
+    "presentation-master": ["universal", "creative"],
+    "storyteller": ["universal", "creative"]
+  }
+}