0003-vibe-coding-plugin-design.md

ADR 0003 — The Vibe Coding plugin (a fourth, non-engineering audience)

• Status: Proposed
• Date: 2026-07-11
• Deciders: devantler-tech maintainers
• Issue: #57 (Part of #49, child 1; relates to roadmap epic #38)

🤖 Generated by the Daily AI Engineer

Source ownership update (2026-11-02): ADR 0006 retires the original separate-source boundary. Maintained skills are authored in their owning plugins; the original date and design rationale below remain the historical record.

Correction (2026-07-18) — the VS Code delivery step is obsolete. D5's child-3 bullet required the plugin README to carry a manual "VS Code delivery step" (copy the companion agent to .github/agents/<name>.agent.md), because ADR-0001 found VS Code could not bundle plugin agents. VS Code has since shipped agent plugins and now loads a plugin's bundled agents/ directory automatically — see the 2026-07-18 correction on ADR 0001. The copy step has been removed from the plugin README; the requirement it satisfied (AC1 coverage of the VS Code surface) is now met by the plugin install itself. The rest of this ADR stands.

Context

#49 asks for a plugin that lets a vibe coder — a user with no technical prerequisite — build apps that run on the devantler-tech stack from conversation alone. The maintainer's framing on that issue is load-bearing:

"Remember Vibe Coding != Agentic Engineering. Vibe coding is a rapid, conversational approach where humans prompt AI to generate code and accept it by feel. In contrast, agentic engineering is a professional discipline where humans design structured AI systems with defined workflows, context management, and automated testing to ensure reliability in production environments."

Everything this marketplace currently offers serves an engineering audience: agentic-engineering (tools for building agentic applications), engineering-practices (practice skills — review, testing, design), and the automated-ai-engineer role defined by ADR-0002 (the autonomous engineer actor). The vibe coder is a fourth, non-engineering audience: they do not read diffs, do not know what a cluster or a pipeline is, and must never need to. #49's acceptance criteria pin that down — popular- assistant support (AC1), needs mapped to technical specifications behind the scenes (AC2), common language not jargon (AC3), devantler-tech conventions followed but abstracted away (AC4), and a hard stay-inside-the-stack boundary with a friendly redirect to filing an issue when a need falls outside it (AC5).

This is epic-shaped, so it follows the decomposition-first precedent (ADR-0001 for bundling mechanics, ADR-0002 for the role/config boundary): this ADR is child 1, documentation-only, and settles the load-bearing decisions — the plugin's shape, where its skills canonically live, where the stack boundary is defined, and the voice contract — so the implementation children have a contract to build against. The original twin skill-family roadmap deferred its decomposition until this ADR settled the shape. Current skill work is tracked in this repository alongside the owning plugin.

Decision

D1 — Shape: a new plugins/vibe-coding agents+skills bundle, a distinct fourth audience

The plugin is a new top-level bundle plugins/vibe-coding — one custom agent (the vibe-coding companion persona) plus the skill family in D2 — not an extension of any existing plugin. The three existing engineering-facing audiences and this one must stay unblurred (the maintainer's vibe-coding ≠ agentic-engineering steer): agentic-engineering is for people building AI systems, engineering-practices for engineers practicing the craft, automated-ai-engineer for the autonomous role itself, and vibe-coding for a non-technical human building a product conversationally. The persona needs an agent definition (a system prompt is where voice and elicitation behaviour live — see D4), so this is an agents+skills unit in the ADR-0001 sense, consumable from Claude Code and Copilot CLI alike (AC1 falls out of the plugin standard, not bespoke work). Its plugin.json carries only name / description / version / author / keywords, component paths omitted and auto-discovered (ADR-0001 D1).

D2 — The skill family and its canonical home

Three skills map directly onto #49's acceptance criteria. Their canonical home is now plugins/vibe-coding/skills/ under the maintained-source rule in ADR 0006. The original separate-source packaging plan is retired.

Skill	What it does	ACs
needs-stack-mapping	Translate plain-language product needs (an outcome, an audience, a workflow) into the deployment's building blocks behind the scenes; the conversation stays in the user's vocabulary	AC2, AC4
allowed-stack-guardrail	Before agreeing to build anything, check the need against the consumer-supplied Stack map (D3); in-stack → proceed; out-of-stack → friendly decline + offer to file an issue on the owning repo	AC5
jargon-free-voice	The conversational register: common language, glossary indirection, outcome-first reporting (D4)	AC3

The Skill column values are the installable slugs (the SKILL.md name and directory), already constrained to the Agent Skills spec's lowercase-letters/ numbers/hyphens charset so this repo's spec-validation gate accepts them as-is in child 2.

The original skill-family roadmap framed this family and deferred its decomposition to this ADR; child 2 supplied its implementation.

D3 — The stack boundary is configuration, not plugin content (ADR-0002's split, reapplied)

The guardrail's procedure (check, decline, redirect) is generic role logic and lives in the skill. The concrete allowed stack is a deployment-owned fact — it names this org's products and changes whenever the portfolio does — so per ADR-0002's genericity/volatility rule it does not ship inside the plugin. Instead the skills are authored against a named, consumer-supplied contract section, the Stack map: a plain-language catalogue of the allowed building blocks (what each is for, in the user's vocabulary — "a place your app runs", "a template a new service starts from"), each with its owning repo so an out-of-stack need can be redirected into a well-formed issue there (AC5's second half). devantler-tech's own Stack map (ksail for clusters/GitOps, the platform's application archetypes, the templates, the site) ships with the deployment (the monorepo), not with the plugin — the stack can evolve weekly without a plugin release, exactly the volatility argument that made ADR-0002's trade acceptable.

The contract, pinned (so child 2 can implement deterministically): the Stack map is a Markdown section titled ## Stack map in the consumer deployment's canonical instructions file (AGENTS.md, reaching each assistant through its native shim — the same channel ADR-0002 chose for deployment-owned configuration). It contains a table whose rows each carry three required fields: Building block (the plain-language name), Good for (what needs it serves, in the user's vocabulary — the matching surface), and Owning repo (owner/repo, where a suggested issue for that block is filed). One additional field is required once per map: a default intake repo — the catch-all owner/repo that receives the suggested issue for any need that matches no row, so AC5's redirect is resolvable even for unmapped needs. Matching is semantic but conservative: the allowed-stack-guardrail skill maps the user's stated need against the rows' Good for purposes, and anything it cannot confidently match falls through to the catch-all decline-and-suggest path. Fail-closed covers the map itself: when the ## Stack map section is absent or malformed (no table, or a row missing a required field), the guardrail treats every need as out-of-stack — it declines plainly, explains that its allowed-stack catalogue is unavailable, and suggests an issue on the default intake repo when one is parseable (otherwise it directs the user to whoever operates the deployment). It never builds best-effort out of stack, and the decline itself stays jargon-free.

D4 — Voice: plain-language-first, glossary indirection, outcomes not artifacts

The persona's conversational contract (agent definition + the voice skill):

• Needs-first elicitation — ask about outcomes, audiences, and workflows, never about technologies; the user should be able to answer every question without technical vocabulary.
• Glossary indirection — technical terms surface only when the user asks "how does it work?", and always with a plain-words explanation; the default register contains no stack nouns (AC3).
• Outcomes, not artifacts — progress is reported as product outcomes ("your app is live at …", "sign-ups now get a confirmation email"), never as engineering artifacts (PRs, pipelines, manifests). The machinery still follows devantler-tech conventions underneath (AC4) — conventions are applied, not discussed.
• The human gate is conversational, not review-shaped — unlike the automated-ai-engineer role (draft-PR checkpoint, a maintainer who reads diffs), the vibe coder approves described behaviour in plain language before it is built and after it ships. The underlying engineering discipline (tests, validation, drafts) is unchanged — it is simply not the user's interface.

D5 — Sequencing (the follow-up children)

• Child 2 — skills: decompose the skill-family plan into the three skills of D2, authored against the Stack map contract section (no devantler-tech specifics in skill bodies).
• Child 3 — assemble: plugins/vibe-coding/ — the companion agent under agents/, the three skills authored in their owning bundle, both manifests + README updated in parity, validated by the standard gate (scripts/validate-manifests.sh, skill spec-validation). Bundled agents/ auto-load only in Claude Code and Copilot CLI (ADR-0001; repo README), so the plugin README must carry the documented VS Code delivery step — copy the companion agent to .github/agents/<name>.agent.md — for AC1's coverage of the marketplace's supported VS Code surface. Superseded 2026-07-18: bundled agents/ auto-load in VS Code too, so AC1's VS Code coverage is met by the plugin install and no delivery step is documented (see the correction note above).
• Child 4 — consume & E2E: author devantler-tech's Stack map in the consuming deployment and validate the plugin end-to-end per the verify-it-works-behaviourally rule — voice and guardrail quality cannot be proven by manifest validation alone. The scenario set covers both sides of the guardrail and its failure mode: an in-stack build (a small app built purely conversationally), an out-of-stack request (asserting the plain-language decline and the suggested-issue payload lands on the owning repo), an unmapped need (asserting the catch-all default-intake redirect), and a missing/malformed Stack map (asserting the fail-closed decline of D3).

This ADR itself changes no manifest, skill, or workflow (documentation-only).

Considered alternatives

• Fold vibe coding into agentic-engineering (or engineering-practices). Rejected: the maintainer's framing makes the audience split load-bearing; those plugins presume an engineering reader, and co-bundling would leak jargon-heavy skills into a persona whose defining constraint is no technical prerequisite.
• Hard-code the devantler-tech stack inside the plugin. Rejected: the allowed stack is the fastest-churning fact in play; baking it in forces a plugin release per portfolio change and breaks reuse by any other deployment — the exact anti-pattern ADR-0002 rejected for the engineer role.
• Author the skills directly in the plugin directory. Originally rejected under the separate-source rule. ADR 0006 supersedes that choice: maintained skills now live in their owning plugins; external skills retain their upstream provenance.
• Skills-only (no agent persona). Rejected: voice and elicitation behaviour are exactly what agent definitions are for; skills alone cannot own the conversational register, and #38 T1's direction is agents+skills bundles.
• A standalone product (site/app) instead of a plugin. Rejected as out of scope for this marketplace: AC1 asks for popular-assistant support, which the tool-neutral plugin standard already delivers; a bespoke app would re-invent the runtime this repo exists to avoid.

Consequences

Positive

• Unlocks a genuinely new, non-engineering audience for the marketplace — the first plugin whose user never reads code — while AC1 (popular assistants) falls out of the existing plugin standard for free.
• The Stack map contract keeps the portfolio's churn out of the plugin (no release per stack change) and makes the plugin reusable by any org that supplies its own map.
• The vibe-coding ≠ agentic-engineering boundary is now written down where future curation can hold the line (naming, non-goals, audience table).

Negative / risks

• A consumer must author a Stack map before the plugin is useful — one-time setup friction; mitigated by devantler-tech's own map landing as the reference implementation in child 4.
• Voice quality is hard to validate mechanically — manifest validation proves nothing about AC3; mitigated by child 4's conversational E2E scenario being part of the definition of done.
• Boundary pressure over time — engineering-flavoured skills will be tempting to bundle here; the audience table in D1 is the curation rule that resists it.

Follow-up

• Child 2 (skills), child 3 (assemble), child 4 (consume & E2E) per D5 — filed when this ADR is accepted.
• The original skill-family decomposition depended on this ADR; current follow-up belongs to this repository under the maintained-source ownership rule.