build-stack-v2
/build-stack-v2
EXPERIMENTAL deterministic builder for a whole n8n workflow STACK (multiple sub-workflows wired via Execute Workflow), JS-orchestrated. Takes a PRP-style end-to-end use case, decomposes it into sub-workflows along known rules, fixes the handover contracts between them, documents the architecture (mermaid) in one central file, then builds each sub-workflow bottom-up via build-workflow-v2. Two modes: GREENFIELD (new stack) and EXTEND (change an existing one). Decomposition rules, build order (topological), and per-sub-WF gates are JS control flow the model cannot skip. Use for multi-workflow use
- Author
- neurawork-git ↗
- Repository
- n8n-autopilot ↗
- Licence
- MIT
- Last repository change
- 15.10.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 15.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: stack.workflow.js
What it does and when to use it
EXPERIMENTAL deterministic builder for a whole n8n workflow STACK (multiple sub-workflows wired via Execute Workflow), JS-orchestrated. Takes a PRP-style end-to-end use case, decomposes it into sub-workflows along known rules, fixes the handover contracts between them, documents the architecture (mermaid) in one central file, then builds each sub-workflow bottom-up via build-workflow-v2. Two modes: GREENFIELD (new stack) and EXTEND (change an existing one). Decomposition rules, build order (topological), and per-sub-WF gates are JS control flow the model cannot skip. Use for multi-workflow use
Arguments
/build-stack-v2 <end-to-end use-case / PRP>" OR extend "<stack id-or-name>" "<change>
Original author description
EXPERIMENTAL deterministic builder for a whole n8n workflow STACK (multiple sub-workflows wired via Execute Workflow), JS-orchestrated. Takes a PRP-style end-to-end use case, decomposes it into sub-workflows along known rules, fixes the handover contracts between them, documents the architecture (mermaid) in one central file, then builds each sub-workflow bottom-up via build-workflow-v2. Two modes: GREENFIELD (new stack) and EXTEND (change an existing one). Decomposition rules, build order (topological), and per-sub-WF gates are JS control flow the model cannot skip. Use for multi-workflow use
How it works
- Why a separate stack builder
- Architecture — roles are extracted
- How to run
- Phases
- Result → Completion Report
- Limits
SKILL.md preview
---
name: build-stack-v2
description: "EXPERIMENTAL deterministic builder for a whole n8n workflow STACK (multiple sub-workflows wired via Execute Workflow), JS-orchestrated. Takes a PRP-style end-to-end use case, decomposes it into sub-workflows along known rules, fixes the handover contracts between them, documents the architecture (mermaid) in one central file, then builds each sub-workflow bottom-up via build-workflow-v2. Two modes: GREENFIELD (new stack) and EXTEND (change an existing one). Decomposition rules, build order (topological), and per-sub-WF gates are JS control flow the model cannot skip. Use for multi-workflow use cases; for a single workflow use build-workflow-v2."
argument-hint: '"<end-to-end use-case / PRP>" OR extend "<stack id-or-name>" "<change>"'
user-invocable: true
allowed-tools: Read, Write, Edit, Grep, Glob, Bash(npx:*), Workflow
---
# Build Stack v2 — JS-Orchestrated Stack Builder
One level up from [`build-workflow-v2`](../build-workflow-v2/SKILL.md): 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`](../stack-intake/SKILL.md) 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
| agentType | Role |
|---|---|
| `n8n-stack-architect` | decompose a PRP into sub-WFs + handover contracts (greenfield) / plan the delta (extend) |
| `n8n-stack-comprehender` | reconstruct the real call-graph from `executeWorkflow` refs in the local mirror (extend) |
| `n8n-author` | (reused) writes the central architecture doc verbatim |
| build-workflow-v2 agents | (reused, one `workflow()` hop per sub-WF) research → author → validate → deploy → test |
## 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
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 `workflowId`s).
**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.
Files in this package (2)
- SKILL.md 12 KB
- stack.workflow.js 30 KB
Versions
The database has no other skills named build-stack-v2.
Database snapshot: 13.11.2026 · package version fa469c98e2bb (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100build-workflow-v2
EXPERIMENTAL deterministic variant of build-workflow + deploy, JS-orchestrated. Two modes: GREENFIELD (new workflow) and EDIT (change an existing one). Phase ordering, gate-checks (validate / drift-safe push --verify), and fix-loop limits are enforced by a Claude Code JS… - 100prp-core-runner
Orchestrate complete PRP workflow from feature request to pull request. Run create branch, create PRP, execute implementation, commit changes, and create PR in sequence. Use when implementing features using PRP methodology or when user requests full PRP workflow. - 100blueprint-prp-execute
Execute a PRP with validation loop, TDD, and quality gates. Use when asked to execute a PRP, run a planned feature from docs/prps/, or delegate a PRP to subagents. - 100prp-pr
Creates and opens GitHub pull requests. Always use when creating a PR on GitHub, when the user explicitly asks to create or open a PR, when another PRP workflow reaches its PR-creation step, or when the user invokes $prp-pr. - 100prp-pr
Creates and opens GitHub pull requests. Always use when creating a PR on GitHub, when the user explicitly asks to create or open a PR, when another PRP workflow reaches its PR-creation step, or when the user invokes /prp-pr. - 100n8n-workflows
Workflows n8n: only when the project uses n8n (stack, not Core Pack). Edit workflow JSON or when the user mentions n8n.