{
  "markdown": "# Quarkus + LangChain4j + AI Stack\n# Version: 0.21.0\n\n## What this repository is\n\nA small, opinionated, distribution-ready artifact for building AI and agent applications on the\nJava stack of **Quarkus + LangChain4j**. It pairs drop-in always-on coding conventions\n(`CLAUDE.md` for Claude, `AGENTS.md` for Codex and Bob) with three skills that set up the\nprerequisites, scaffold new projects and components, and audit existing projects — all from\nworking templates. The conventions and templates reflect real-world Quarkus + LangChain4j\npractice and a baseline of modern Java, so the guidance captures how these systems are actually\nbuilt rather than generic boilerplate.\n\n## Quick install — any skills-capable agent\n\n[![Skills](https://www.skills.sh/b/eldermoraes/quarkus-agentic-scaffolding)](https://www.skills.sh/eldermoraes/quarkus-agentic-scaffolding)\n\nThe fastest install on any agent that supports the [Agent Skills](https://agentskills.io) format —\nClaude Code, Codex, GitHub Copilot, Cursor, Windsurf, opencode, Amp, IBM Bob, and dozens more:\n\n```\nnpx skills add eldermoraes/quarkus-agentic-scaffolding\n```\n\nThe [skills.sh](https://www.skills.sh/) CLI detects your agents and installs all three skills\n(`setup-agentic-scaffolding`, `scaffold-project`, `audit-project`) into each of them — IBM Bob\nincluded, as a first-class agent. Two things it does **not** set up, which\n`/setup-agentic-scaffolding` (below) handles for you: the always-on conventions file (`CLAUDE.md`\nfor Claude, `AGENTS.md` for everything else) that lands in your project root, and the required MCP\ntooling (Quarkus Agents MCP + context7).\n\n## The flow\n\nThree skills, run in order the first time and revisited as needed:\n\n- **`/setup-agentic-scaffolding`** — user-invoked; run once per machine, then re-visit per\n  project. Verifies the toolchain (JDK 25 / GraalVM, JBang, a container runtime), registers the\n  Quarkus Agents MCP + context7 for your agent, and drops the conventions file into your project.\n- **`/scaffold-project`** — creates a new Quarkus + LangChain4j project end-to-end, and also\n  auto-triggers when you ask to add a component (an AI service, tool, agent/workflow, RAG\n  pipeline, MCP client or server, or guardrail) to an existing project.\n- **`/audit-project`** — user-invoked; points at an *existing* project and reports how it\n  conforms to (or is ready to adopt) the conventions, fixing findings only after you confirm.\n\n**Two invocation forms.** How you installed the skills decides the slash-command name in Claude\nCode: a **skills-CLI install** (the Quick install above) gives bare names —\n`/setup-agentic-scaffolding`, `/scaffold-project`, `/audit-project`; a **plugin install** (the\nper-agent sections below) namespaces them by the plugin id — `/quarkus-agentic-scaffolding:setup-agentic-scaffolding`,\n`/quarkus-agentic-scaffolding:scaffold-project`, `/quarkus-agentic-scaffolding:audit-project`. Both refer to the same\nskills; use whichever your install produced.\n\n## How to use with Claude\n\n**Install the skills (plugin).** Add this repository as a plugin marketplace and install it:\n\n```\n/plugin marketplace add eldermoraes/quarkus-agentic-scaffolding\n/plugin install quarkus-agentic-scaffolding@eldermoraes\n```\n\nAll three skills and the `scaffold-project` `templates/` are installed and auto-discovered. (Or\nuse the [Quick install](#quick-install--any-skills-capable-agent) above, which works for Claude\nCode too.)\n\n**Set up the prerequisites.** Run `/setup-agentic-scaffolding` (or\n`/quarkus-agentic-scaffolding:setup-agentic-scaffolding` on a plugin install) — it verifies the toolchain,\nregisters the **Quarkus Agents MCP** and **context7** MCP servers, and drops `CLAUDE.md` into your\nproject root. `CLAUDE.md` §1 makes those two MCP servers non-negotiable for this stack, and the\nsetup skill is what puts them in place.\n\n*Manual fallback,* if you would rather wire it by hand: register the Quarkus Agents MCP with the\npinned command\n`claude mcp add -s user quarkus-agent -- jbang --java 21+ io.quarkus:quarkus-agent-mcp:1.2.5:runner`;\nadd context7 with `claude mcp add -s user context7 -- npx -y @upstash/context7-mcp@4.0.3` (for higher rate limits\n`export CONTEXT7_API_KEY=…` in your shell — the server picks it up from the environment, so no key\nbelongs on the command line); optionally install superpowers with\n`/plugin marketplace add obra/superpowers-marketplace` then\n`/plugin install superpowers@superpowers-marketplace`; and copy [`CLAUDE.md`](CLAUDE.md) into your\nproject root yourself (Claude only auto-loads it from a project root or `~/.claude/`, so no plugin\ncan ship it for you).\n\nQuarkus also ships the server as a Claude plugin — `/plugin marketplace add\nquarkusio/quarkus-agent-mcp` then `/plugin install quarkus-agent@quarkus-tools`. Two things to know\nbefore you pick that route over the command above. It launches `jbang quarkus-agent-mcp@quarkusio`,\nand that alias resolves `io.quarkus:quarkus-agent-mcp:RELEASE:runner`, so what runs is whatever was\nnewest when the server started — two machines set up a week apart run different code. And it passes\nno `--java`: the alias *does* declare `java-version: 21+`, but JBang 0.125.x ignores that for a GAV\nscript-ref, so the server runs on JBang's default JDK 17 and dies with `UnsupportedClassVersionError`\nunless whatever launched it happens to export a JDK 21+ `JAVA_HOME`. Use one route or the other, not\nboth — the plugin's server and a `claude mcp add` entry are both named `quarkus-agent`, so uninstall\nthe plugin (`/plugin uninstall quarkus-agent@quarkus-tools`) before registering by hand.\n\n**Try it.** Open your project and use a trigger phrase such as *\"scaffold a new Quarkus +\nLangChain4j project\"*, *\"create a new AI service\"*, or *\"set up a new RAG pipeline\"* —\n`scaffold-project` produces the layout and starter files, and `CLAUDE.md` governs the conventions\nof the code that follows. To review an existing project, run `/audit-project`.\n\n## How to use with Codex\n\n**Install the skills (plugin).** Add this repository as a Codex plugin marketplace, then install\nthe plugin from the plugins list:\n\n```\ncodex plugin marketplace add eldermoraes/quarkus-agentic-scaffolding\n```\n\nOpen Codex, run `/plugins`, select the `eldermoraes` marketplace, and install `quarkus-agentic-scaffolding`.\nAll three skills and the `scaffold-project` `templates/` are auto-discovered. (Codex also\nauto-discovers skills placed under `.agents/skills/`, and the [Quick install](#quick-install--any-skills-capable-agent)\nworks for Codex too.)\n\n**Set up the prerequisites.** Run `/setup-agentic-scaffolding` — it verifies the toolchain,\nregisters the **Quarkus Agents MCP** and **context7** MCP servers for Codex, and drops `AGENTS.md`\ninto your project root. `AGENTS.md` §1 makes those two MCP servers non-negotiable for this stack.\n\n*Manual fallback:* add the Quarkus Agents MCP with `codex mcp add quarkus-agent -- jbang --java 21+ io.quarkus:quarkus-agent-mcp:1.2.5:runner`;\nadd context7 with `codex mcp add context7 -- npx -y @upstash/context7-mcp@4.0.3` (for higher rate limits\n`export CONTEXT7_API_KEY=…` in your shell — the server picks it up from the environment, so no key\nbelongs on the command line); install/enable the Superpowers plugin if you use it; and copy\n[`AGENTS.md`](AGENTS.md) into your project root (Codex reads project instructions from the project\ntree).\n\n**Try it.** Use a trigger phrase such as *\"scaffold a new Quarkus + LangChain4j project\"* or\n*\"create a new AI service\"*; `scaffold-project` produces the layout and starter files and\n`AGENTS.md` governs the conventions. Run `/audit-project` to review an existing project.\n\n## How to use with Bob\n\nIBM Bob reads the same `AGENTS.md` that Codex does, so the conventions are shared. Bob is a\nfirst-class agent in the skills CLI, so the [Quick install](#quick-install--any-skills-capable-agent)\n(`npx skills add eldermoraes/quarkus-agentic-scaffolding`) installs all three skills into\n`.bob/skills/` for you — that is the recommended path.\n\n**Set up the prerequisites.** Run `/setup-agentic-scaffolding` — it verifies the toolchain,\nregisters the **Quarkus Agents MCP** and **context7** MCP servers for Bob, and drops `AGENTS.md`\ninto your project root. If you already added `AGENTS.md` for Codex, the same file serves Bob — there\nis no separate `BOB.md`.\n\n*Manual fallback:* register both servers with Bob's own CLI (Bob 2.0.0), which writes the file Bob\nactually reads:\n\n```\nbob mcp add -s global quarkus-agent jbang -- --java 21+ io.quarkus:quarkus-agent-mcp:1.2.5:runner\nbob mcp add -s global context7 npx -- -y @upstash/context7-mcp@4.0.3\nbob mcp list\n```\n\nThe `--` is required: without it Bob parses `--java` as one of its own options and exits with\n`error: unknown option '--java'`.\n\n**Trade-off (stated explicitly):** `-s global` writes `~/.bob/settings/mcp.json` and registers both\nservers for **every workspace on the machine**, not just this project. That is the default here\nbecause these MCP servers are tools, not conventions — they answer Quarkus and library questions\nand change nothing in projects that never call them — and re-registering them per project is\nfriction. If you mix stacks and want nothing of this artifact reaching your other work, register at\nworkspace scope instead: `-s workspace` is Bob's own default, so dropping the flag means the same\nthing — it registers in the current project only. One caveat at that scope: Bob does not create\n`<project>/.bob/mcp.json`, so the command dies with `ENOENT … .bob/mcp.json` when the file is\nmissing. Seed it **only if it is missing** — `>` truncates, and an existing file holds\nregistrations worth keeping:\n\n```\n[ -f .bob/mcp.json ] || { mkdir -p .bob && printf '{\"mcpServers\":{}}\\n' > .bob/mcp.json; }\n```\n\nAt global scope Bob creates the file and its directory for you. On a name that is already\nregistered, `add` refuses (`Error: MCP server \"quarkus-agent\" already exists`) — to *replace* a\nstale entry use `bob mcp add-json`, which overwrites in place. One form per server:\n\n```\nbob mcp add-json -s global quarkus-agent '{\"command\":\"jbang\",\"args\":[\"--java\",\"21+\",\"io.quarkus:quarkus-agent-mcp:1.2.5:runner\"]}'\nbob mcp add-json -s global context7 '{\"command\":\"npx\",\"args\":[\"-y\",\"@upstash/context7-mcp@4.0.3\"]}'\n```\n\nRead what `bob mcp list` prints, not just the names: an entry from an older setup shows its own\ncommand, and a stale command is exactly the case `add-json` is for — on **either** server. For\n`quarkus-agent` that looks like an unpinned `jbang quarkus-agent-mcp@quarkusio`; for `context7` it\nis an older version pin, and that is the *frequent* one — the `@upstash/context7-mcp` pin moves\nwith every upstream release (Renovate keeps this guide current), so a machine set up before the\nlatest bump holds the previous version until you overwrite it.\n\nTo write the JSON by hand instead, the global file is `~/.bob/settings/mcp.json` and the project\nfile is `<project>/.bob/mcp.json` (a same-named server at project scope overrides global). Older\nBob docs name `mcp_settings.json` in that same settings directory; Bob 2.0.0 treats it as legacy and\nmigrates it **only when `mcp.json` does not yet exist**, so on a machine that already has `mcp.json`\nanything written to the legacy name is silently ignored. That cuts both ways, so **look before you\nregister**: if `~/.bob/settings/mcp_settings.json` exists and `mcp.json` does not, start Bob once and\nlet it migrate (it says so — *\"your global MCP configuration has been migrated to mcp.json\"*) before\nrunning any `bob mcp add`. Adding first creates `mcp.json` yourself, and the migration then never\nruns — your old servers stay in the legacy file, unread. If you set Bob up with a version of this\nguide before v0.18.0, also look for `~/.bob/mcp.json` and `~/.bob/mcp_settings.json` — one directory\nabove `settings/`, which is where we used to point you; Bob reads neither, so a registration sitting\nthere has never loaded. Contents either way:\n\n```json\n{\n  \"mcpServers\": {\n    \"quarkus-agent\": { \"command\": \"jbang\", \"args\": [\"--java\", \"21+\", \"io.quarkus:quarkus-agent-mcp:1.2.5:runner\"] },\n    \"context7\":      { \"command\": \"npx\",   \"args\": [\"-y\", \"@upstash/context7-mcp@4.0.3\"] }\n  }\n}\n```\n\n(`jbang` must be on the PATH of whatever *starts* Bob — install it with a package manager, e.g.\n`sdk install jbang` or `brew install jbang`. A GUI-launched client gets a minimal PATH that contains\nnone of the usual install locations, so if the server fails with `spawn jbang ENOENT`, put the\nabsolute path from `command -v jbang` in `command` and keep the args as they are. `--java 21+` is not\noptional: the MCP server is compiled for Java 21, and JBang\nresolves its own JDK — it falls back to its default, currently 17, whenever the process that spawned\nit hands over no `JAVA_HOME`, which is exactly what Bob and other GUI-launched clients do. For higher\nrate limits `export CONTEXT7_API_KEY=…` in your environment rather than writing a literal key into\nthe file; the server reads it from there.) If the skills CLI is\nunavailable, the repository's fallback helper installs all three\nskills into `.bob/skills/` for you:\n\n```\n# Pick one — the three forms are alternatives, not a sequence; uncomment the one you want\n# ./scripts/install-bob-skill.sh                   # into <cwd>/.bob/skills/\n# ./scripts/install-bob-skill.sh /path/to/project  # into that project's .bob/skills/\n# ./scripts/install-bob-skill.sh --global          # into ~/.bob/skills/\n```\n\nBob asks for approval before activating a skill — once per conversation, not once ever; the setting\nis a single global toggle rather than a per-skill grant. Two things to know while you are here: a\nskill's `description` front-matter field is load-bearing (Bob ignores a skill without one), and\nskills are only available in Bob's **Advanced** mode.\n\n**Try it.** Use a trigger phrase such as *\"scaffold a new Quarkus + LangChain4j project\"*;\n`scaffold-project` produces the layout and starter files and `AGENTS.md` governs the conventions.\nRun `/audit-project` to review an existing project.\n\n## What's in `CLAUDE.md` / `AGENTS.md` and why\n\n`CLAUDE.md` (Claude) and `AGENTS.md` (Codex and Bob) are intentionally short and always-on. They\ncarry the same project conventions, expressed for the instruction surface each agent reads. Each\nsection earns its place:\n\n- **§1 Required tooling (mandatory).** Makes `context7` and the **Quarkus Agents MCP** required,\n  not optional: every Quarkus task goes through the Quarkus Agents MCP and every library lookup\n  through `context7`, with `superpowers` skills used where applicable. If a required tool is\n  missing, work stops rather than falling back to stale model memory.\n- **§2 Java conventions.** Sets Java 25 as the *minimum*, makes **virtual threads** the default\n  carrier for blocking work, prefers **Scoped Values** over `ThreadLocal`, gives a pragmatic\n  stance on structured concurrency, and favors **records / sealed types / pattern matching**.\n  These are the modern-Java habits that make AI code simpler and more debuggable.\n- **§3 Quarkus conventions.** Platform BOMs over pinned versions, CDI-first wiring, Quarkus REST +\n  OpenAPI, WebSockets Next for streaming, the `-parameters` flag, a dual JVM/native build,\n  zero-code AI observability via Micrometer + OpenTelemetry, and turning off Dev Services when a\n  real model endpoint is configured.\n- **§4 LangChain4j conventions.** Declarative `@RegisterAiService` over manual wiring, declarative\n  **agentic** composition for multi-agent workflows, typed structured output, named/right-sized\n  models, a streaming pattern that keeps reactive types at the edge, declarative fault tolerance\n  on AI-service methods, and **Easy RAG first**.\n- **§5 Testing.** A minimal intended baseline (`@QuarkusTest` + REST-assured + native ITs),\n  flagged as a target rather than an observed standard.\n- **§6 Scope and overrides.** States that per-project deviations are allowed when documented\n  inline — the conventions guide, they do not imprison.\n\n## What the skills do and how they compose with the conventions\n\nThe three skills split along the **invocation axis**, and all defer to the always-on convention\nfile for the active agent rather than restating the rules — a single source of truth per agent:\nscaffolding and setup in the skills, rules in `CLAUDE.md` or `AGENTS.md`.\n\n- **`setup-agentic-scaffolding`** (user-invoked) prepares the environment the other two skills\n  depend on: it checks the toolchain, registers the Quarkus Agents MCP + context7 for the agent\n  you are running, and writes the conventions file (seeded from byte-for-byte copies inside the\n  skill folder) into your project. It is the one skill that legitimately runs *before* the MCP\n  exists — that is its job.\n- **`scaffold-project`** (model-invoked umbrella) handles the *\"create something new\"* moments. It\n  is deliberately a single skill covering **both** ends of creation: bootstrapping a new project\n  end-to-end (delegating skeleton, BOMs, and the native profile to the Quarkus Agents MCP, then\n  applying the repo's package layout, `application.properties` baseline, non-extension deps, and\n  starter templates), **and** adding components to an existing project — an AI service, tool,\n  agent/workflow, RAG pipeline, MCP client or server, or guardrail. Keeping creation and\n  components together (owner decision) minimizes the number of skills you face; it stays\n  model-invoked so component requests auto-trigger.\n- **`audit-project`** (user-invoked) is read-only by default: it audits an existing project\n  against §2–§5, the package layout, and the dependency/properties baseline, and reports\n  prioritized findings with evidence and a suggested fix each — applying fixes only after you\n  confirm, by handing off to `scaffold-project`'s component sections. Platform upgrades (an EOL\n  Quarkus line, an unsupported Java release, pre-BOM LangChain4j) have no such handoff: they stay\n  your own step.\n\nThe split between skill and conventions is deliberate and non-overlapping:\n\n- **The skills are procedural** — they tell the agent (Claude, Codex, or Bob) *how to set up,\n  lay things out, and get them running*, and point at the Quarkus Agents MCP to actually create\n  and run the project.\n- **`CLAUDE.md` / `AGENTS.md` are declarative** — they state the conventions the resulting code\n  must follow (`CLAUDE.md` for Claude, `AGENTS.md` for Codex and Bob).\n\nFor Codex distribution, `.agents/plugins/marketplace.json` points to `plugins/quarkus-agentic-scaffolding/`.\nThat directory is only a lightweight wrapper with symlinks back to `.codex-plugin/` and `skills/`,\nso the Claude and Codex packages share the same skill content. Bob has a marketplace, but it\ndistributes modes and MCP servers rather than skills (and is IBM-internal), so there is no\nmarketplace channel for skills: Bob's are installed by the skills CLI (or\n`scripts/install-bob-skill.sh`) into `.bob/skills/`.\n\n## Advanced — personal use (optional global install)\n\nA power user who works *exclusively* in this stack can apply the conventions globally instead of\ncopying the file into each project:\n\n- **Claude** — move the contents of `CLAUDE.md` into the global `~/.claude/CLAUDE.md`.\n- **Codex** — move the contents of `AGENTS.md` into `~/.codex/AGENTS.md`.\n- **Bob** — move the contents of `AGENTS.md` into `~/.bob/AGENTS.md`, Bob's documented global\n  context file. (Bob also loads global *rules* from `~/.bob/rules/`, so\n  `~/.bob/rules/quarkus-langchain4j.md` works too if you would rather keep them separate from your\n  general context.) Install the skills globally with `./scripts/install-bob-skill.sh --global`\n  (into `~/.bob/skills/`), and add the shared MCP servers with the `bob mcp add -s global` commands\n  from [How to use with Bob](#how-to-use-with-bob) — not by hand in the **MCP** tab, which is how a\n  registration ends up without the `--java 21+` pin.\n\n**Trade-off (stated explicitly):** the global files apply to **all** work on your machine or\nagent profile. If you also work in other stacks (other languages, frameworks, or non-AI Java\nprojects), these Quarkus/LangChain4j-specific rules will bleed into unrelated work. For anyone who\nmixes stacks, the per-project drop-in is recommended over the global install.\n\n**Precedence.** A project-root convention file is read *in addition to* a global one, and project\nguidance can override broader global rules. To undo a global install, see\n[Uninstall](#uninstall) — the same managed-block procedure applies to `~/.claude/CLAUDE.md`,\n`~/.codex/AGENTS.md`, and `~/.bob/AGENTS.md` or `~/.bob/rules/<your-file>.md`.\n\n## Uninstall\n\nRemoves **this artifact only**. Everything it helped you set up is shared with the rest of your\nwork and stays: **JDK 25 / GraalVM**, **JBang**, your container runtime, the **Quarkus Agents MCP**\nand **context7** MCP servers, `superpowers`, and every project `/scaffold-project` generated. No\nstep below touches them — that is deliberate. If you also want the two MCP servers gone, remove\nthem with your agent's own MCP commands; nothing here does it for you.\n\n| Removed | Where it lives |\n|---|---|\n| The three skills, per agent | `.claude/skills/`, `.agents/skills/`, `.bob/skills/`, … project and global |\n| Plugin + marketplace (Claude) | `quarkus-agentic-scaffolding@eldermoraes` |\n| Plugin + marketplace (Codex) | `quarkus-agentic-scaffolding@eldermoraes` |\n| Extension (Gemini CLI) | `quarkus-agentic-scaffolding` |\n| The managed conventions block | `CLAUDE.md` / `AGENTS.md` in your project root |\n| The global conventions, if you did the [Advanced](#advanced--personal-use-optional-global-install) install | `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.bob/AGENTS.md` or `~/.bob/rules/<your-file>.md` |\n\nThe MCP config files `/setup-agentic-scaffolding` may have written are **kept**: `.cursor/mcp.json`,\n`opencode.json`, and Bob's `.bob/mcp.json` (project) or `~/.bob/settings/mcp.json` (global).\nDeleting them would remove exactly what this boundary protects — and for the two Bob files that is\nnot even the whole story: `bob mcp add` merges into whatever is already there, so a global\n`~/.bob/settings/mcp.json` typically holds servers that have nothing to do with this artifact\n(possibly with credentials in them). If you do want our two servers gone, remove them **by entry**,\nnever by file: `bob mcp remove -s global quarkus-agent` and `bob mcp remove -s global context7`\n(`-s workspace` for a project file), then `bob mcp list` to confirm what remains.\n\n### 1. The skills\n\nUse the path you installed with — or all of them, if you are not sure. Every command here is\nsafe to run when nothing is installed.\n\n**Skills CLI** (the [Quick install](#quick-install--any-skills-capable-agent)) — name the three\nskills:\n\n```\nnpx skills remove setup-agentic-scaffolding scaffold-project audit-project -y\nnpx skills remove -g setup-agentic-scaffolding scaffold-project audit-project -y\nnpx skills list\nnpx skills list -g\n```\n\nThe first line covers the current project, the second your global install. Removal deletes real\nfiles, not just symlinks. Omitting `-a/--agents` is intentional: the CLI then cleans the skills out\nof *every* agent it knows about, including ghost symlinks left by an agent it no longer detects.\n\n> **Do not use `--all` here.** It removes **every** skill from your agents, including skills that\n> have nothing to do with this repository — and, contrary to its own `--help`, it does not imply\n> `-y`. Name the three skills.\n\n**Claude Code** — uninstall the plugin, then drop the marketplace:\n\n```\n/plugin uninstall quarkus-agentic-scaffolding@eldermoraes\n/plugin marketplace remove eldermoraes\n/reload-plugins\n```\n\n> Removing a marketplace in Claude Code **uninstalls every plugin installed from it** and deletes\n> its cached clone. That is harmless here — this marketplace ships one plugin — but if you added\n> other plugins from `eldermoraes`, they go with it.\n\nVerify with `claude plugin list`. Your MCP servers live in `~/.claude.json` under `mcpServers`,\nwhich is untouched by any of this.\n\n**Codex** — remove the plugin **first**, then the marketplace:\n\n```\ncodex plugin remove quarkus-agentic-scaffolding@eldermoraes\ncodex plugin marketplace remove eldermoraes\ncodex plugin list\n```\n\n> Codex behaves the opposite way from Claude: removing the marketplace does **not** uninstall\n> anything. It drops `[marketplaces.eldermoraes]` from `~/.codex/config.toml` and deletes the\n> Codex-managed marketplace directory, which leaves any other plugin from that marketplace\n> **orphaned** — its cache and config survive, its source does not. Remove the plugins first.\n\n`codex plugin remove` has no `rm` or `uninstall` alias, and marketplace removal is CLI-only (there\nis no `/plugins` equivalent). Your MCP servers stay in `[mcp_servers.*]` in `config.toml`.\n\n**Bob** — Bob has no command for this: a skill is a directory it scans for, so removing the\ndirectory is the whole uninstall.\n\n```\n# Pick one — the three forms are alternatives, not a sequence; uncomment the one you want\n# ./scripts/uninstall-bob-skill.sh                   # from <cwd>/.bob/skills/\n# ./scripts/uninstall-bob-skill.sh /path/to/project  # from that project's .bob/skills/\n# ./scripts/uninstall-bob-skill.sh --global          # from ~/.bob/skills/\nls .bob/skills/                                      # verify; and: ls ~/.bob/skills/\n```\n\nNothing named `setup-agentic-scaffolding`, `scaffold-project`, or `audit-project` should be left in\nthat listing — a directory Bob does not see is a skill Bob does not load. `ls` answering `No such\nfile or directory` is a pass too: it means this project never had a local `.bob/skills/`, which is\nexactly what you should see if you only ever installed with `--global`.\n\nIt removes only the three skills it installed, and only after reading each `SKILL.md`'s front-matter\n`name`: a directory that declares a different name — or declares none, or has no `SKILL.md` at all —\nis skipped with a warning rather than deleted. What the check cannot do is tell two identical\ndeclarations apart, so a skill of your own that *also* declares `name: audit-project` is\nindistinguishable from ours and **will** be removed. Move it aside before you run this. A symlinked\nskill is unlinked, not recursed into. Your MCP registration (`.bob/mcp.json` in a project,\n`~/.bob/settings/mcp.json` globally), `.bob/rules/`, and every other skill in `.bob/skills/` are\nleft alone. Re-running it is a clean no-op. Skills load once per conversation, so\n**start a new conversation** in Bob afterwards.\n\n**Gemini CLI** — if you installed the extension, uninstalling it takes the two MCP servers it\ndeclares with it, so add them back at user scope:\n\n```\ngemini extensions uninstall quarkus-agentic-scaffolding\ngemini mcp add -s user quarkus-agent jbang --java 21+ io.quarkus:quarkus-agent-mcp:1.2.5:runner\ngemini mcp add -s user context7 npx -y @upstash/context7-mcp@4.0.3\ngemini extensions list\ngemini mcp list\n```\n\nOrder matters — uninstall first, then re-add. A `settings.json` registration takes precedence over\nan extension-declared server of the same name, so re-adding *before* uninstalling would silently\nshadow the extension's pinned versions. `gemini mcp add` defaults to `--scope project`, hence\n`-s user`. In `gemini mcp list`, an entry labelled `(from quarkus-agentic-scaffolding)` is still\ncoming from the extension; after a successful uninstall and re-add, both servers appear without\nthat label. Restart the session.\n\n### 2. The conventions file\n\nThe file in your project root is **yours**. `/setup-agentic-scaffolding` only owns the region\nbetween its two markers:\n\n```text\n<!-- BEGIN quarkus-agentic-scaffolding conventions … -->\n…\n<!-- END quarkus-agentic-scaffolding conventions -->\n```\n\nRemoving that region is the uninstall. Deleting the file is optional, and only safe when nothing\nelse is in it. Run these from your project root, on `CLAUDE.md` (Claude) or `AGENTS.md` (Codex,\nBob, Gemini, Cursor, opencode). For the [Advanced](#advanced--personal-use-optional-global-install)\ninstall, substitute the global path — `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, or\n`~/.bob/AGENTS.md` (or `~/.bob/rules/<your-file>.md`, if you used a rules file instead).\n\n**Run these one fence at a time, and do not paste the section as a whole.** Each of the five steps\nbelow is conditional on what the step before it printed, so a single paste would run the removal\nwithout you having read the precheck, and then hand the original file straight back.\n\nSteps 1 and 2 are the safe pair — a copy and a report, neither of which changes `CLAUDE.md`:\n\n```bash\n# 1. Back up, without clobbering an existing .bak\ncp CLAUDE.md \"CLAUDE.md.backup-$(date +%Y%m%d-%H%M%S)\"\n\n# 2. Precheck — proceed ONLY on OK-SAFE-TO-REMOVE\nawk '/^<!-- BEGIN quarkus-agentic-scaffolding conventions/{b++;bl=NR}\n     /^<!-- END quarkus-agentic-scaffolding conventions/{e++;el=NR}\n     END{printf \"BEGIN=%d END=%d beginLine=%d endLine=%d -> %s\\n\", b,e,bl,el,\n         (b==1 && e==1 && bl<el) ? \"OK-SAFE-TO-REMOVE\" : \"REFUSE - remove the block by hand\"}' CLAUDE.md\n```\n\nRead that line before going on. Run step 3 **only** if it printed `OK-SAFE-TO-REMOVE`; on `REFUSE`,\nstop here and edit the file by hand.\n\n```bash\n# 3. Remove — changes nothing unless a complete, in-order pair exists\nperl -i -0777 -pe 's/^<!-- BEGIN quarkus-agentic-scaffolding conventions.*?^<!-- END quarkus-agentic-scaffolding conventions -->[ \\t]*\\r?\\n?//msg' CLAUDE.md\n```\n\nNow compare what is left against the backup:\n\n```bash\n# 4. Inspect what the removal changed\ndiff \"$(ls -t CLAUDE.md.backup-* | head -1)\" CLAUDE.md\n```\n\nDeleting the file itself is optional, and the line below does it only if no content is left. Run it\n**only** once the diff has shown you that nothing of yours was inside the deleted region and that\nnothing but whitespace remains:\n\n```bash\n# 4b. Drop the file itself only if nothing but whitespace is left\ngrep -q '[^[:space:]]' CLAUDE.md || rm CLAUDE.md\n```\n\n**Read the diff before you trust it.** A large deletion is the expected result, so its size tells\nyou nothing about whether it went right. What you are checking for is *your own writing* in the\ndeleted lines. If you see any, step 5 is the recovery — it puts the original file back verbatim,\nmanaged block included, and you then remove the block by hand:\n\n```bash\n# 5. Restore, if the diff shows anything you wrote\ncp \"$(ls -t CLAUDE.md.backup-* | head -1)\" CLAUDE.md\n```\n\n**Keep the backup** until you have restarted your agent and confirmed it still behaves. There is\ndeliberately no `rm` step for it.\n\n**On `REFUSE`, do not run step 3** — edit the file by hand instead. `REFUSE` means the markers are\nmissing, duplicated, out of order, or on the same line, and no automated edit can tell a real block\nfrom a passage where you wrote *about* the markers. Step 3 is built to change nothing in that case,\nbut the point of the precheck is that you never find out the hard way. The reverse does not hold:\n`OK-SAFE-TO-REMOVE` says a marker pair exists *in order*, not that the pair is genuine — a marker\nquoted at column 0, say inside a fenced code block where you documented your own agent setup, counts\nas real to both commands, and step 3 then takes everything between it and its partner. That is why\nstep 1's backup is not optional and why the diff has to be read.\n\nTwo more things worth knowing:\n\n- **If `CLAUDE.md` is a symlink,** in-place editing replaces it with a regular file and breaks the\n  link. Edit the target instead.\n- **`CLAUDE.md` is often not in git.** Do not count on `git checkout` to undo this — that is what\n  the backup in step 1 is for.\n\nStep 4 uses `grep -q '[^[:space:]]'` rather than a size test on purpose: a file containing only the\nblock reduces to exactly 0 bytes, but a block with a blank line on each side leaves a 2-byte\nwhitespace-only file. Interior blank lines double up after removal; that is cosmetic, and yours to\ntidy.\n\n### 3. Verify\n\n```bash\nnpx skills list          # and: npx skills list -g\nclaude plugin list\ncodex plugin list\ngemini extensions list\ngemini mcp list\ngrep -rIn 'quarkus-agentic-scaffolding' . --exclude-dir=.git\n```\n\nNone of the first five should mention `quarkus-agentic-scaffolding`, and `gemini mcp list` should\nshow `quarkus-agent` and `context7` **without** a `(from …)` label. The `grep` should return\nnothing but your own backups. Restart your agent — most of them read skills, plugins, and\ninstruction files once at startup.\n\n## What's inside\n\n```\n.\n├── README.md                 # This file\n├── CLAUDE.md                 # Always-on project conventions (drop into your project root)\n├── AGENTS.md                 # Codex/Bob equivalent of the always-on project conventions\n├── CONTRIBUTING.md           # How to propose changes\n├── CHANGELOG.md              # Release history\n├── LICENSE                   # Apache-2.0\n├── .gitignore\n├── .claude-plugin/           # Claude installable-plugin + marketplace manifests\n│   ├── plugin.json\n│   └── marketplace.json\n├── .codex-plugin/            # Codex plugin manifest\n│   └── plugin.json\n├── gemini-extension.json     # Gemini CLI extension manifest (declares the MCP servers)\n├── .agents/\n│   └── plugins/\n│       └── marketplace.json  # Codex repo-local marketplace manifest\n├── plugins/\n│   └── quarkus-agentic-scaffolding/  # Codex marketplace wrapper; symlinks to .codex-plugin + skills\n├── scripts/\n│   ├── install-bob-skill.sh    # Fallback: copy the skills into a project's (or global) .bob/skills/\n│   └── uninstall-bob-skill.sh  # The mirror: remove them again (see Uninstall)\n├── docs/\n│   └── VALIDATING-TEMPLATES.md   # How to verify the templates still build\n└── skills/\n    ├── setup-agentic-scaffolding/   # User-invoked: prerequisites (toolchain, MCP, conventions)\n    │   ├── SKILL.md\n    │   └── templates/\n    │       ├── conventions-CLAUDE.md    # Byte-for-byte seed copy of root CLAUDE.md\n    │       └── conventions-AGENTS.md    # Byte-for-byte seed copy of root AGENTS.md\n    ├── scaffold-project/            # Create projects + add components (model-invoked umbrella)\n    │   ├── SKILL.md\n    │   └── templates/\n    │       ├── pom.xml.template\n    │       ├── application.properties.template\n    │       ├── AiService.java.template\n    │       ├── AiServiceTest.java.template\n    │       ├── Agent.java.template\n    │       ├── McpClient.java.template\n    │       ├── McpServer.java.template\n    │       ├── Tools.java.template\n    │       ├── Guardrails.java.template\n    │       └── RagSetup.java.template\n    └── audit-project/               # User-invoked: audit an existing project vs the conventions\n        └── SKILL.md\n```\n\n## Versioning and changelog\n\nThis artifact uses semantic versioning. `README.md`, `CLAUDE.md`, `AGENTS.md`, the three\n`skills/*/SKILL.md` files (`setup-agentic-scaffolding`, `scaffold-project`, `audit-project`),\n`.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, and `gemini-extension.json` each carry\na matching version header — nine files, enforced in CI by `ci/check-version-consistency.sh`. See\n[`CHANGELOG.md`](CHANGELOG.md) for release history.\n\n## License\n\nLicensed under the **Apache License 2.0**. See [`LICENSE`](LICENSE) for the full text.\n\n## Contributing\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md) for how to propose changes to the conventions, the skills,\nand the templates — including how to keep new patterns evidence-backed, and how to confirm the\ntemplates still build (see [`docs/VALIDATING-TEMPLATES.md`](docs/VALIDATING-TEMPLATES.md)).\n",
  "bytes": 35460,
  "sha": "d617ce9b1307e050ac124e57abda3e67284fd212c4231b3e64cca54fb0e8f3fb",
  "repo_slug": "eldermoraes/quarkus-agentic-scaffolding",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_eldermoraes_quarkus_agentic_scaffolding_f270144b/readme"
}