| name | n8n-builder-planning-gate |
| description | Standardizes how `n8n-builder` performs planning triage, specialist consultation, and produces plan v0 plus post–v0 edit round; mandatory `cro-loop` runs at execution intent before Stage C. Use when n8n-builder is in Stage A (planning). |
| version | 1 |
n8n-builder Planning Gate
This skill defines the planning contract that n8n-builder follows in
Stage A. It produces plan v0 on disk (feeds the CRO loop runbook
when the user signals implementation) and the structure the execution-gate skill
relies on at dispatch time.
When to use
- The user has invoked
n8n-builder (explicit entrypoint).
- The task carries an n8n signal (workflow, node, MCP, n8n-as-code).
- No plan v0 exists yet for the current
task_id.
If a plan v0 already exists for the episode, do not re-run this skill —
either revise v0 in-place per user feedback (post–v0 edit round) or, when
the user signals implementation, proceed to the CRO loop.
Required plan structure
The plan file lives at
<project>/.opencode/docs/plans/YYYY-MM-DD-n8n-<slug>.md and MUST contain the
following sections in this order:
- Context — one paragraph: what is changing in n8n and why.
- Problem Framing — bulleted list of the constraints, conflicts, and
unknowns that motivate the design.
- Scope — bulleted list of files, workflow ids, environments, and node
families in scope.
- Out of Scope — bulleted list of explicit non-goals.
- Assumptions — bulleted list. Each assumption is a falsifiable
statement. Mark each as
verified or pending.
- Mode and Environment — declared mode (
as-code / mcp-live /
hybrid), env (dev / staging / prod), and the justification per
n8n-builder-mode-policy.yml selection rules.
- Risks & Mitigations — table:
| Risk | Impact | Mitigation | Owner |
- Phase Dependency Graph — table with columns:
| Group | Phase ID | Depends on | Parallel siblings | Touches (disjoint across siblings) | Mode |
- Implementation Phases — for each phase:
- Metadata block (required):
id: short stable id (e.g. P2a)depends_on: list of phase ids that must complete beforeparallelizable_with: list of sibling phase idstouches: bounded list of file globs and/or workflow idsrollback_scope: files / artifacts reverted on rollback (subset of
touches)mode: one of as-code, mcp-live, hybridenv: one of dev, staging, prodworker_cap: integer ≤ mode cap (≤ 4 for mcp-live, ≤ 8 for as-code)destructive: boolean; if true, list affected workflow idsrequires_review: boolean (true for as-code by default)requires_qa: boolean (true for as-code by default)
- Goal (1 sentence)
- Steps (numbered, with
what / why / files / acceptance)
- Verification (specific commands or checks)
- Rollback (specific reversal steps using
rollback_scope)
- Verification Strategy (Cross-Phase) — bulleted list.
- Rollback Strategy (Cross-Phase) — bulleted list.
- Open Questions — explicit user-facing questions that block planning.
- Open Risks (auto-populated by CRO bookkeeping; may be empty at v0).
- Execution Gate (Post-Plan) — declare the two-choice gate
(
phase-by-phase vs all-phases-approved) the user will choose after
the CRO loop completes (CRO runs when user signals implementation, not immediately after v0).
Specialist consultation triggers
Invoke specialists in parallel via Task. Pass minimal briefs only;
never the entire plan dump. Use the subagent-response-protocol envelope.
| Trigger condition | Specialist |
|---|
| Workflow boundary, sub-workflow design, retry/idempotency at workflow level, integration contracts | vp-architecture |
| Credentials, webhook auth, allowlisted node review, untrusted input handling, secret references | ciso |
| Concurrency, queue depth, throughput, partial failure handling, per-node timeout strategy | vp-engineering |
| Logging, metrics, alerting, runbook integration, rollout / rollback strategy | sre-lead |
| As-code artifact maintainability, naming, sub-workflow abstraction, expression-node simplification | staff-engineer |
| Repeated patterns across workflows, template extraction, generators, reusable sub-workflows | vp-platform |
| n8n version specifics, node API specifics, vendor docs, MCP capability lookups | vp-research (always — only broker for external docs) |
| Existing Jira / Confluence / Bitbucket context referenced in the plan | atlassian-pm (read-only) |
Skip a specialist if its domain does not apply. Never invoke "for show".
Never lateral-call. Specialists may not call each other; they return findings
to n8n-builder.
Output contract for plan v0
The plan artifact (input to cro-loop when the user signals implementation) is preferably the markdown file under <project>/.opencode/docs/plans/; prompt-only full plan text is valid when disk is unavailable — pass stable body + hash to cro. Additionally, n8n-builder
must return a structured handoff envelope (used internally by the CRO loop
runbook) containing:
plan_handoff:
plan_path: "<project>/.opencode/docs/plans/YYYY-MM-DD-n8n-<slug>.md"
plan_hash: "<sha256 of plan markdown>"
task_id: "<episode task id>"
mode: as-code | mcp-live | hybrid
env: dev | staging | prod
affected_workflow_ids: [ ... ]
node_family_set: [ ... ]
credential_aliases: [ ... ]
specialist_bundle_refs:
- agent: vp-architecture
ref: "<ref id or path>"
open_questions: [ ... ]
status: ready_for_post_v0_edit_round
The handoff is structured data, not a free-form chat blob. Secret values are
forbidden; aliases only.
Self-check (before persisting v0)
Validate before writing:
Post–v0 edit round (planning)
After v0 is settled (file or prompt-only), ask once whether the user wants to add, remove, or
change anything; revise v0 until satisfied. Do not ask for approve v0 for CRO.
When the user signals implement / execute / proceed with implementation,
start the cro-loop immediately as the next step (before Stage C) — see
n8n-builder agent Stage B.
Cross-references
