Build Stack v2 — JS-Orchestrated Stack Builder

One level up from build-workflow-v2: that ships ONE workflow, this ships a whole stack — an orchestrator plus the sub-workflows it calls via Execute Workflow nodes, with the handover contracts fixed and the architecture documented. The pipeline is a Claude Code Workflow JS script (stack.workflow.js); the script body is the control flow, each step a typed subagent. The per-sub-workflow build reuses build-workflow-v2's build.workflow.js / edit.workflow.js verbatim (one workflow() hop each), so every sub-workflow gets the same hard gates.

Need a plan to feed this? If the user has only a rough idea, run /n8n-autopilot:stack-intake first — a guided interview that produces the PRP-style description this skill digests.

Why a separate stack builder

A single workflow that does everything is a maintenance trap: untestable in parts, OOM-prone, no reuse. The decomposition rules (single-responsibility leaves, triggers at the edges, fan-out/fan-in, error + large-data boundaries — from n8n-orchestration-patterns) say when to split. This skill applies them structurally: the architect decomposes, the contracts are fixed before any code, and the build runs bottom-up by topological sort — a parent is only built after its children exist, because its Execute Workflow node needs the child's real workflowId. A failed child halts its dependents (no building on a broken foundation) and escalates.

Architecture — roles are extracted

How to run

1. Detect the mode from $ARGUMENTS:
   • Starts with extend / names an existing stack + a change → EXTEND.
   • Otherwise (a use-case description) → GREENFIELD.
   • If ambiguous or empty, ask the user (or point them at /n8n-autopilot:stack-intake).
   • Greenfield auto-detect: before decomposing, the script checks docs/*.architecture.md for a stack that already covers the use-case. On a match it returns status: 'needs-decision' instead of rebuilding — relay the hint (re-run as EXTEND with the change, or pass mode: 'greenfield' to force a fresh build). This stops the silent rebuild-over-a-working-stack case. 1b. Refresh the instance cache. A stack decomposition that cannot see the instance will rebuild jobs that already run there:

   bash "${CLAUDE_PLUGIN_ROOT}/scripts/build-instance-cache.sh"

   Writes .n8n-autopilot/instance-cache.json + instance-brief.md; the architect reuses existing workflows as callees from it. If it fails, report that before starting — do not plan blind.

2. Resolve the three sub-script paths. They are siblings of this skill inside the plugin install:

   • buildScript = <plugin>/skills/build-workflow-v2/build.workflow.js
   • editScript = <plugin>/skills/build-workflow-v2/edit.workflow.js
   • syncScript = <plugin>/skills/mirror-sync/sync.workflow.js

   Resolve <plugin> as the absolute parent of this skill dir (build-stack-v2). The script has no fs/__dirname, so these MUST be passed in as args — that is by design.

   Windows / CRLF — do this unconditionally: normalize all three scripts into the scratchpad (sed 's/\r$//' <src> > <scratchpad>/<name>) and pass the scratchpad paths (including as buildScript / editScript / syncScript). Installed copies arrive with CRLF despite the LF pin in .gitattributes, and Workflow({scriptPath}) then refuses them with "script contains control characters". It is sporadic — sync.workflow.js was CRLF in 5.3.0/5.3.1 and LF in 5.3.2 — so a version that happened to work is no reason to skip this. Never hand-edit the plugin cache.

3. Invoke stack.workflow.js via the Workflow tool (scriptPath = absolute path to it; it runs in the consumer-repo cwd so npx n8nac workspace status resolves the pinned project + sync folder):

   Greenfield:

   Workflow({
     scriptPath: "<plugin>/skills/build-stack-v2/stack.workflow.js",
     args: {
       description: "<full end-to-end use-case / PRP>",
       buildScript: "<plugin>/skills/build-workflow-v2/build.workflow.js",
       specPath: "<path to the authoritative spec, if one exists in the repo>",
       referenceStack: "<folder/glob of a PROVEN twin stack, if one exists>"
     }
   })

   Extend:

   Workflow({
     scriptPath: "<plugin>/skills/build-stack-v2/stack.workflow.js",
     args: {
       mode: "extend",
       target: "<stack id or name hint>",
       change: "<what to change>",
       buildScript: "<plugin>/skills/build-workflow-v2/build.workflow.js",
       editScript: "<plugin>/skills/build-workflow-v2/edit.workflow.js",
       syncScript: "<plugin>/skills/mirror-sync/sync.workflow.js",
       specPath: "<authoritative spec>",
       referenceStack: "<proven twin>",
       activate: false
     }
   })

   specPath / referenceStack are not optional garnish — pass them whenever the repo has them. Without the spec the fan-out re-derives requirements from prose (observed: a real requirement argued away because a sibling stack lacked it); without the reference twin every sub-agent re-researches node contracts instead of mirroring a pattern that already runs in production.

   activate — greenfield defaults to true (a new stack is useless inactive); extend defaults to false because an existing stack's active/inactive state is a deliberate operational choice. Pass activate: true on extend when the change is supposed to go live now.

4. Render the Completion Report from the returned object. Watch live progress with /workflows. status: 'success' means built + deployed, not proven: sub-workflows report proven: false because the stack no longer live-tests each one with synthetic data. Prove the stack ONCE, end to end, against the entry trigger with real input — that single run is the acceptance criterion.

Phases

Preflight (both modes, runs first): resolves and logs the target env + project before anything is created. A stack run rewires a whole project, so pointing it at the wrong one is the most expensive mistake available here — and it used to be silent. enforce-env.sh refuses un-pinned instance commands, but only once a build agent already runs, by which point the abort reads as an unrelated tool error. The resolved target is logged up front and returned as envContext in every report. A missing per-session N8NAC_ENVIRONMENT is called out explicitly: the run would otherwise follow the SHARED global active env, which another session can change mid-run.

Greenfield (stack.workflow.js): Plan (n8n-stack-architect decompose → stackPlan) → Document (docs/<stack>.architecture.md — contracts + mermaid, composed deterministically in JS) → Build (topological bottom-up, one build.workflow.js hop per sub-WF with deferActivation, children's real ids fed to parents) → Activate (deps-first: callees before callers — n8n refuses to activate a caller whose callee is not published, so per-sub-workflow activation would fail on order alone) → Report (re-write the doc with real workflowIds).

Extend (stack.workflow.js): Mirror (mirror-sync so the local call-graph is complete) → Comprehend (n8n-stack-comprehender reconstructs the DAG from executeWorkflow refs) → Plan (n8n-stack-architect delta) → Build (new sub-WFs bottom-up via build.workflow.js, then changed sub-WFs / orchestrator rewiring via edit.workflow.js with deferTest) → Activate (only with activate: true) → Report (update the doc).

A change that is already present is a no-op, not a failure. edit.workflow.js returns { status: 'success', noop: true } and skips deploy/test when the author finds the change already in the file (comprehend refreshed it to remote base, so local == remote). They appear in the result's noops[]. Treating those as failures used to HALT the whole stack — four in one observed run.

Local-mirror invariant (EXTEND). The call-graph is reconstructed from code, not memory — so the repo must mirror the instance first. stack.workflow.js runs mirror-sync as phase 0; if a referenced child has no local file, the comprehender reports missingLocal and you should re-run mirror-sync.

Result → Completion Report

The script returns one of:

• { status: 'aborted', reason } — missing input (no description / no change / no buildScript).
• { status: 'needs-decision', reason: 'existing-stack', stackSlug, entryWorkflowId, detail, hint } — greenfield was requested but a matching stack already exists locally. Relay the hint verbatim; do NOT rebuild. Re-run as EXTEND, or pass mode: 'greenfield' to force.
• { status: 'needs-decision', reason: 'empty-comprehension', target, envContext, attention } — EXTEND found no existing stack in the active environment's mirror. Do NOT re-run as greenfield to "make it work": the delta planner would have classified every sub-WF as new and rebuilt the whole stack against whatever project the session points at. Check envContext, re-run mirror-sync, or choose greenfield deliberately.
• { status: 'failed', stage, reason, … } — a structural failure (dependency cycle in the plan).
• { status: 'partial', … attention } — some sub-WFs built green, a failure halted the rest. Surface attention + the per-sub-WF list verbatim; offer to fix the failing sub-WF and resume.
• { status: 'success', mode, stackSlug, entry, architectureDoc, buildOrder, subWorkflows[], idMap, … }.

Render success:

## Stack {mode === 'extend' ? 'extended' : 'built'} & wired (build-stack-v2)

**Stack:** {stackSlug}   **Entry:** {entry}
**Architecture doc:** {architectureDoc}
**Build order:** {buildOrder.join(' → ')}

| sub-workflow | status | workflowId | url |
|---|---|---|---|
{ each subWorkflows/applied row }

{ if any non-success: "⚠ {attention}" }
{ if missingLocal: "⚠ Mirror gap: <list> — re-run /n8n-autopilot:mirror-sync." }

Each sub-workflow's own live-test outcome lives in its build.workflow.js result (the stack records status + id + url; deep test detail is per-sub-WF). Open the architecture doc for the mermaid + contracts.

Limits

• Built on build-workflow-v2. It inherits v2's boundary: gates enforce that steps run in order, not that the authored TS is semantically perfect. Per-sub-WF correctness rests on the node-verifier fan-out inside each build.
• workflow() nesting is 1 level. stack → build/edit/sync is fine (those use only agent()). Do not add a workflow() call inside build/edit.
• Mid-run human steps (a sub-WF with an mcpTrigger needs a UI Publish; non-HTTP triggers need a manual run) are handed back per sub-WF, not driven inside the stack run.
• Experimental, and test-gated — end-to-end stack runs should only be trusted once build-workflow-v2 (greenfield + edit) is green against the target instance and the skills: pass-through is verified.