From 918d262968184746a8bbcab436d479ca5f25e062 Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm Date: Sat, 11 Jul 2026 16:32:36 +0200 Subject: [PATCH 1/2] docs(adr): design the Vibe Coding plugin (shape, skill family, stack guardrail, voice) Co-Authored-By: Claude Fable 5 --- docs/adr/0003-vibe-coding-plugin-design.md | 161 +++++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 docs/adr/0003-vibe-coding-plugin-design.md diff --git a/docs/adr/0003-vibe-coding-plugin-design.md b/docs/adr/0003-vibe-coding-plugin-design.md new file mode 100644 index 0000000..58dca5b --- /dev/null +++ b/docs/adr/0003-vibe-coding-plugin-design.md @@ -0,0 +1,161 @@ +# ADR 0003 β€” The Vibe Coding plugin (a fourth, non-engineering audience) + +- **Status:** Proposed +- **Date:** 2026-07-11 +- **Deciders:** devantler-tech maintainers +- **Issue:** [#57](https://github.com/devantler-tech/agent-plugins/issues/57) (Part of [#49](https://github.com/devantler-tech/agent-plugins/issues/49), child 1; twin skill-family roadmap: [agent-skills#56](https://github.com/devantler-tech/agent-skills/issues/56); relates to roadmap epic [#38](https://github.com/devantler-tech/agent-plugins/issues/38)) + +> πŸ€– Generated by the Daily AI Engineer + +## Context + +[#49](https://github.com/devantler-tech/agent-plugins/issues/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 twin roadmap item on the skills side is +[agent-skills#56](https://github.com/devantler-tech/agent-skills/issues/56), which decomposes after +this ADR settles shape (its stated sequencing). + +## 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 (agent-skills, bundled β€” never hand-copied) + +Three skills, mapping directly onto #49's acceptance criteria, with their **canonical home in +[agent-skills](https://github.com/devantler-tech/agent-skills)** per this marketplace's +single-source-of-skills rule; the plugin bundles them via `gh skill install`: + +| 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 | + +[agent-skills#56](https://github.com/devantler-tech/agent-skills/issues/56) already frames exactly this +family and defers its decomposition to this ADR; child 2 executes it there. + +### 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 guardrail **fails closed**: a need that maps to nothing in the Stack +map is declined kindly and captured as a suggested issue β€” never built 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 [agent-skills#56](https://github.com/devantler-tech/agent-skills/issues/56) + 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 bundled from agent-skills, both manifests + README updated in parity, validated by the + standard gate (`scripts/validate-manifests.sh`, skill spec-validation). +- **Child 4 β€” consume & E2E:** author devantler-tech's Stack map in the consuming deployment and + validate the plugin end-to-end with a real vibe-coder scenario (a small app built purely + conversationally), per the verify-it-works-behaviourally rule β€” voice and guardrail quality cannot be + proven by manifest validation alone. + +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.** Rejected: violates the marketplace's + single-source-of-skills rule; agent-skills is the canonical home and plugins bundle, never hand-copy. +- **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. +- [agent-skills#56](https://github.com/devantler-tech/agent-skills/issues/56) decomposition unblocks + once this ADR lands (its stated dependency). From d66c9a85d61ac49e5fe96ae3aecc0a8ab194ac90 Mon Sep 17 00:00:00 2001 From: Nikolai Emil Damm Date: Sat, 11 Jul 2026 18:22:34 +0200 Subject: [PATCH 2/2] docs(adr): pin the Stack map contract, spec-valid slugs, VS Code delivery, both-sides E2E --- docs/adr/0003-vibe-coding-plugin-design.md | 45 +++++++++++++++++----- 1 file changed, 35 insertions(+), 10 deletions(-) diff --git a/docs/adr/0003-vibe-coding-plugin-design.md b/docs/adr/0003-vibe-coding-plugin-design.md index 58dca5b..c187776 100644 --- a/docs/adr/0003-vibe-coding-plugin-design.md +++ b/docs/adr/0003-vibe-coding-plugin-design.md @@ -60,9 +60,13 @@ single-source-of-skills rule; the plugin bundles them via `gh skill install`: | 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 | +| **`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](https://agentskills.io/specification)'s lowercase-letters/ +numbers/hyphens charset so this repo's spec-validation gate accepts them as-is in child 2. [agent-skills#56](https://github.com/devantler-tech/agent-skills/issues/56) already frames exactly this family and defers its decomposition to this ADR; child 2 executes it there. @@ -79,9 +83,24 @@ owning repo so an out-of-stack need can be redirected into a well-formed issue t 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 guardrail **fails closed**: a need that maps to nothing in the Stack -map is declined kindly and captured as a suggested issue β€” never built best-effort out of stack, and -the decline itself stays jargon-free. +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 @@ -107,11 +126,17 @@ The persona's conversational contract (agent definition + the voice skill): specifics in skill bodies). - **Child 3 β€” assemble:** `plugins/vibe-coding/` β€” the companion agent under `agents/`, the three skills bundled from agent-skills, both manifests + README updated in parity, validated by the - standard gate (`scripts/validate-manifests.sh`, skill spec-validation). + 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/.agent.md` + β€” for AC1's coverage of the marketplace's supported VS Code surface. - **Child 4 β€” consume & E2E:** author devantler-tech's Stack map in the consuming deployment and - validate the plugin end-to-end with a real vibe-coder scenario (a small app built purely - conversationally), per the verify-it-works-behaviourally rule β€” voice and guardrail quality cannot be - proven by manifest validation alone. + 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).