docs(adr): design the Vibe Coding plugin (shape, skill family, stack guardrail, voice)

docs/adr/0003-vibe-coding-plugin-design.md

@@ -0,0 +1,186 @@
+# 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 |
+
+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.
+
+### 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 [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). 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.
+- **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.** 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).