bmad-method-quarkus 1.0.1 → 1.0.3

package/src/bmm-skills/agents/bmad-quarkus-dev/skills/quarkus-sql-jdbc-agroal/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: quarkus-sql-jdbc-agroal
-description: Standard for executing SQL queries, updates, batches, and transactions in Quarkus WITHOUT Panache or any ORM — using the Agroal connection pool with plain JDBC (default) or the reactive Vert.x SQL client (justified cases only). Use this skill whenever the user writes or reviews ANY repository, DAO, SQL statement, SELECT/INSERT/UPDATE/DELETE, batch operation, transaction, pagination query, jsonb access, connection pool configuration, or mentions Agroal, JDBC, PreparedStatement, datasource, or "query the database" — all persistence code must follow these patterns, including repository/adapter/row-mapper naming.
+description: Standard for executing SQL queries, updates, batches, and transactions in Quarkus WITHOUT Panache or any ORM — using the Agroal connection pool with plain JDBC (default) or the reactive Vert.x SQL client (justified cases only). Use this skill whenever the user writes or reviews ANY repository, DAO, SQL statement, SELECT/INSERT/UPDATE/DELETE, batch operation, transaction, pagination query, jsonb access, connection pool configuration, or mentions Agroal, JDBC, PreparedStatement, datasource, or "query the database" — all persistence code must follow these patterns. Data access lives in the slice `<Slice>Sql` class with `Connection` as the first parameter of every method (see quarkus-hexagonal-core skill); there are no repositories, DAOs or row-mapper classes.
 ---
 
 # SQL Execution Standard: Agroal + Plain JDBC (No ORM)
 
 Applies to any Quarkus backend project; project directives (CLAUDE.md, ADRs, explicit instructions) override these defaults where they conflict.
 
-Persistence is explicit SQL through the Agroal pool. No Panache, no Hibernate, no reflection-based row mappers. Repositories are adapters in `infrastructure/persistence` implementing outbound ports (see quarkus-hexagonal-core skill).
+Persistence is explicit SQL through the Agroal pool. No Panache, no Hibernate, no reflection-based row mappers. Data access lives in the slice's `<Slice>Sql` class — the driven adapter of the vertical slice (see quarkus-hexagonal-core skill). There are no `*Repository` ports and no `Jdbc*` adapters: one `Sql` class per slice, called only by that slice's `Handler`.
 
 One clarification to keep teams from chasing ghosts: **Agroal is a JDBC (blocking) pool** — there is no "reactive Agroal". The reactive path in Quarkus is the Vert.x SQL client (`quarkus-reactive-pg-client`) with its own pool. Default choice here is **Agroal + JDBC** (simpler, dominant skill base, works perfectly in native); reactive client only for measured hot paths with extreme concurrency (see §7).
 
@@ -42,131 +42,149 @@ Rules:
 
 ## 2. Injection and the golden resource pattern
 
-Inject the pool, never raw drivers, never `DriverManager`:
+Inject the pool, never raw drivers, never `DriverManager`. The `Sql` class holds the `DataSource` but **does not open connections** — the `Handler` opens exactly one per business operation and passes it in (see §3):
 
 ```java
 @ApplicationScoped
-public class JdbcUserRepository implements UserRepository {
+public class CreatePartyIndividualSql {
 
-    private final AgroalDataSource ds;
-    public JdbcUserRepository(AgroalDataSource ds) { this.ds = ds; }
+    @Inject
+    DataSource dataSource;      // injected for symmetry/health checks; connections come from the Handler
 }
 ```
 
-Every statement uses **try-with-resources on Connection, PreparedStatement AND ResultSet** — this is what returns connections to the pool. A missed close under load exhausts the pool and takes the native pod down:
+**Every method's first parameter is `Connection conn`.** That signature is the contract the `Handler` must honour exactly — same name, order, arity and types. Statements use **try-with-resources on PreparedStatement AND ResultSet** (the `Connection` is owned and closed by the caller). A missed close under load exhausts the pool and takes the native pod down:
 
 ```java
-private static final String FIND_BY_ID = """
-    SELECT id, email, status, created_at
-    FROM app_user
-    WHERE id = ?
+private static final String SELECT_PARTY_BY_ID = """
+    SELECT id, tenant_id, party_type, status, created_at
+      FROM customer.party
+     WHERE id = ?
+       AND tenant_id = ?
     """;
 
-@Override
-public Optional<User> findById(UserId id) {
-    try (var con = ds.getConnection();
-         var ps  = con.prepareStatement(FIND_BY_ID)) {
-        ps.setObject(1, id.value());
-        try (var rs = ps.executeQuery()) {
-            return rs.next() ? Optional.of(mapRow(rs)) : Optional.empty();
+public PartyDto findPartyById(Connection conn, UUID id, String tenantId) throws SQLException {
+    try (PreparedStatement ps = conn.prepareStatement(SELECT_PARTY_BY_ID)) {
+        ps.setObject(1, id);
+        ps.setString(2, tenantId);
+        try (ResultSet rs = ps.executeQuery()) {
+            return rs.next() ? mapRow(rs) : null;
         }
-    } catch (SQLException e) {
-        throw translate("user.find_by_id", e);
     }
 }
 ```
 
 Absolute rules:
-- SQL as `private static final String` text blocks. Never concatenate user input — `PreparedStatement` placeholders ALWAYS (SQL injection + plan cache).
+- SQL as `private static final String` text blocks (comma-first concatenation is equally acceptable), schema-qualified. Never concatenate user input — `PreparedStatement` placeholders ALWAYS (SQL injection + plan cache).
+- Quote reserved-word schemas and tables: `"order".party`. Verify the real schema name before writing the query.
 - Dynamic WHERE clauses: build from a whitelist of column/operator constants, values still as placeholders.
-- One private `mapRow(ResultSet) -> Entity` per repository (or a `RowMapper<T>` functional interface shared via a tiny helper — see §6). No reflection mappers: they break native and hide cost.
+- Methods declare `throws SQLException` and never catch it — the `Handler` translates it (§8). No `commit`, `rollback` or `setAutoCommit` here, ever.
+- One private `mapRow(ResultSet) -> Dto` per `Sql` class. Rows map to the slice's own DTOs; there is no separate domain entity and no `*RowMapper` class. No reflection mappers: they break native and hide cost.
 
 Naming (canonical rules in the quarkus-hexagonal-core skill):
 
 | Artifact | Convention | Example |
 |---|---|---|
-| Outbound port | `<Entity>Repository`, in `application/port/out` | `UserRepository` |
-| JDBC adapter | `Jdbc<Port>`, in `infrastructure/persistence` | `JdbcUserRepository` |
-| Shared row mapper | `<Entity>RowMapper` (private `mapRow` when not shared) | `UserRowMapper` |
-| SQL constant | `UPPER_SNAKE_CASE` verb-first `private static final String` | `FIND_BY_ID`, `INSERT_USER` |
-| Table / column | `snake_case`, singular table name | `app_user`, `created_at` |
+| Data access class | `${SERVICE_CLASS_PREFIX}Sql`, in the slice folder | `CreatePartyIndividualSql` |
+| Method | imperative verb, matching the query | `insertParty`, `findPartyById`, `listPartiesByTenant` |
+| SQL constant | `UPPER_SNAKE_CASE` matching the method, `private static final String` | `SELECT_PARTY_BY_ID`, `INSERT_PARTY` |
+| Table / column | `snake_case`, singular table name, schema-qualified | `customer.party`, `created_at` |
+| Row target | the slice's `*Dto` | `PartyDto` |
 | Technical exception | `PersistenceException` + specific subtypes (§8) | `TransientPersistenceException` |
 
-Never name a repository `*Dao`, `*Manager` or `*Service` — `*Service` is reserved for use-case implementations, and a repository that grows business logic is a use case in disguise.
+Never name this class `*Repository`, `*Dao`, `*Manager` or `*Service` — those suffixes are banned by the core skill's ArchUnit rules. An `Sql` class that grows an `if` encoding a business rule has swallowed logic that belongs in the `Handler`.
 
-## 3. Transactions: on the use case, not the repository
+## 3. Transactions and connections: one of each, on `Handler.process()`
 
-The unit of work is the business operation. Annotate the **application-layer use case**:
+The unit of work is the business operation, which in a slice is `process()`. The `Handler` opens **one** `Connection` in `execution()` and passes it to every `Sql` call:
 
 ```java
 @ApplicationScoped
-public class RegisterUserService implements RegisterUserUseCase {   // impl = *Service, port = *UseCase
-
-    @Transactional
-    public UserId register(RegisterUserCommand cmd) {
-        var user = User.register(cmd);       // domain
-        userRepository.save(user);           // same tx
-        eventPublisher.publish(new UserRegistered(user.id())); // same tx (outbox insert)
-        return user.id();
+public class CreatePartyIndividualHandler {
+
+    @Inject DataSource dataSource;
+    @Inject CreatePartyIndividualSql sql;
+
+    @Transactional                                    // the ONLY @Transactional in the slice
+    public CreatePartyIndividualResponseDto process(CreatePartyIndividualRequestDto request) {
+        validate(request);
+        return getResult(execution(request));
+    }
+
+    private UUID execution(CreatePartyIndividualRequestDto request) {
+        try (Connection conn = dataSource.getConnection()) {          // exactly one, for the whole operation
+            UUID partyId = sql.insertParty(conn, request.getTenantId(), "Individual",
+                "Active", request.getCreatedBy());
+            sql.insertIndividual(conn, partyId, request.getGivenName(), request.getFamilyName());
+            sql.insertOutboxEvent(conn, partyId, "party", EVENT_TYPE, payloadJson(partyId, request), traceparent());
+            return partyId;
+        } catch (SQLException e) {
+            throw SqlStateTranslator.translate("PTY-500-001", e);      // unchecked -> container rolls back
+        }
     }
 }
 ```
 
-With `@Transactional` active, Agroal enlists the connection in the JTA transaction automatically — repositories keep using `ds.getConnection()` and all writes inside the use case share one transaction, committed/rolled back together. This is exactly what the outbox pattern requires (see quarkus-kafka-messaging skill).
+**Why the explicit `Connection` parameter (performance):** inside an active JTA transaction Agroal returns the *same* enlisted connection for every `getConnection()` call, so both styles cost one physical connection. The difference shows on **read paths that carry no `@Transactional`** — there, a per-method `ds.getConnection()` takes *N* pool leases for *N* queries, each with its own acquisition and return. Passing `conn` makes every path, transactional or not, cost exactly one lease. It also keeps session state (`statement_timeout`, prepared-statement cache, temp tables) coherent across the operation.
 
-- Runtime exceptions roll back by default; domain exceptions extend `RuntimeException`, so throwing them rolls back — correct by construction.
-- Programmatic control when annotations don't fit (loops with per-item commit, batch jobs):
+- `@Transactional` goes on `process()` only — never on a private method (CDI interceptors don't fire on self-invocation, so the transaction would silently never open), never on the `Sql` class.
+- **Read-only slices skip `@Transactional` entirely.** A single `SELECT`, or several reads that tolerate a non-repeatable view, are cheaper without a JTA transaction — still one `Connection`, opened and closed in `execution()`. Add the annotation the moment there is a write, or when several reads must see one snapshot.
+- Runtime exceptions roll back by default; `BusinessException` extends `RuntimeException`, so throwing it rolls back — correct by construction. A checked `SQLException` would **not** roll back, which is why §8 translation is mandatory.
+- Programmatic control when annotations don't fit (loops with per-item commit, batch jobs) — from a `common/` bean or a `*Job`, never from inside a slice `Handler`:
 
 ```java
-QuarkusTransaction.requiringNew().timeout(30).run(() -> { ...repos... });
+QuarkusTransaction.requiringNew().timeout(30).run(() -> { ...sql calls... });
 ```
 
-- Never call `con.commit()`/`setAutoCommit()` manually inside JTA-managed code paths.
-- Read-only single queries need no `@Transactional` (auto-commit read is fine); multi-read consistency or any write → transaction.
+- Never call `con.commit()`/`rollback()`/`setAutoCommit()` anywhere. The core skill ships a CI `grep` gate for exactly these three tokens.
 
 ## 4. Updates, inserts, upserts, generated keys
 
 ```java
-private static final String INSERT = """
-    INSERT INTO app_user (id, email, status, created_at)
-    VALUES (?, ?, ?, ?)
-    ON CONFLICT (email) DO NOTHING
+private static final String INSERT_PARTY = """
+    INSERT INTO customer.party (tenant_id, party_type, status, created_by, updated_by)
+         VALUES (?, ?, ?, ?, ?)
+      RETURNING id
     """;
 
-@Override
-public void save(User u) {
-    try (var con = ds.getConnection(); var ps = con.prepareStatement(INSERT)) {
-        ps.setObject(1, u.id().value());
-        ps.setString(2, u.email().value());
-        ps.setString(3, u.status().name());
-        ps.setObject(4, u.createdAt());
-        if (ps.executeUpdate() == 0) throw new DuplicateEmailException(u.email());
-    } catch (SQLException e) {
-        throw translate("user.save", e);
+public UUID insertParty(Connection conn, String tenantId, String partyType,
+                        String status, String createdBy) throws SQLException {
+    try (PreparedStatement ps = conn.prepareStatement(INSERT_PARTY)) {
+        ps.setString(1, tenantId);
+        ps.setString(2, partyType);
+        ps.setString(3, status);
+        ps.setString(4, createdBy);
+        ps.setString(5, createdBy);
+        try (ResultSet rs = ps.executeQuery()) {
+            rs.next();
+            return rs.getObject("id", UUID.class);
+        }
     }
 }
 ```
 
-- Check `executeUpdate()` counts — 0 rows on an expected UPDATE is a bug or a concurrency signal, not a success.
-- Prefer DB-generated values via `RETURNING` (Postgres) over `getGeneratedKeys()` when you need them: `INSERT ... RETURNING id` + `executeQuery()`.
-- Optimistic locking: `version` column, `UPDATE ... WHERE id = ? AND version = ?`; 0 rows → `StaleVersionException` (domain) → 409 via the unified handler. Do NOT name it `ConcurrentModificationException` — it shadows `java.util.ConcurrentModificationException` and an accidental import turns the 409 mapping into a 500.
-- Upserts: `ON CONFLICT ... DO UPDATE` explicitly; never SELECT-then-INSERT races.
+- **Generated ids**: when the PK has a database default (`id uuid DEFAULT customer.uuidv7() NOT NULL`), exclude `id` from the column list and never bind it. Read it back with `RETURNING id` + `executeQuery()` — preferred over `getGeneratedKeys()`.
+- Check `executeUpdate()` counts — 0 rows on an expected UPDATE is a bug or a concurrency signal, not a success. The `Handler` decides what that means; `Sql` just returns the count.
+- Optimistic locking: `version` column, `UPDATE ... WHERE id = ? AND version = ?`; 0 rows → the `Handler` throws `StaleVersionException` (code-carrying, in `common/exception`) with the slice's conflict code → 409 via its dedicated mapper (see quarkus-error-handling-i18n skill). It is not SQLState-derived — no `SQLException` occurs, so `SqlStateTranslator` never sees it; the `Handler` checks the update count. Do NOT name it `ConcurrentModificationException` — it shadows `java.util.ConcurrentModificationException` and an accidental import turns the 409 mapping into a 500.
+- Upserts: `ON CONFLICT ... DO UPDATE` explicitly; never SELECT-then-INSERT races. A unique-violation (`23505`) surfacing as a `SQLException` is translated by the `Handler` (§8), not swallowed here.
 
 ## 5. Batches, pagination, jsonb
 
 **Batch** (bulk inserts/updates — outbox relays, imports):
 
 ```java
-try (var con = ds.getConnection(); var ps = con.prepareStatement(INSERT)) {
-    for (var item : items) {
-        bind(ps, item);
-        ps.addBatch();
+public int[] insertPartiesBatch(Connection conn, List<PartyDto> items) throws SQLException {
+    try (PreparedStatement ps = conn.prepareStatement(INSERT_PARTY)) {
+        for (PartyDto item : items) {
+            bind(ps, item);
+            ps.addBatch();
+        }
+        return ps.executeBatch();   // add ?reWriteBatchedInserts=true to the JDBC URL (Postgres)
     }
-    ps.executeBatch();          // add ?reWriteBatchedInserts=true to the JDBC URL (Postgres)
 }
 ```
 
-Chunk batches (500–1000) inside long jobs; combine with `QuarkusTransaction` per chunk.
+Chunk batches (500–1000) inside long jobs; combine with `QuarkusTransaction` per chunk, driven from a `*Job` in `common/`, not from a slice `Handler`.
 
 **Pagination**: keyset over OFFSET for anything user-facing/deep:
 
@@ -192,15 +210,17 @@ Read side: `rs.getString("context")` then parse. Index jsonb lookups you actuall
 To kill boilerplate, ONE small internal helper class (~50 lines) per service or shared lib is the sanctioned maximum:
 
 ```java
-public final class Jdbc {
+public final class Jdbc {   // common/util — the one sanctioned exception to the banned-suffix rule
     @FunctionalInterface public interface RowMapper<T> { T map(ResultSet rs) throws SQLException; }
 
-    public static <T> Optional<T> queryOne(DataSource ds, String sql, RowMapper<T> m, Object... params) { ... }
-    public static <T> List<T> queryList(DataSource ds, String sql, RowMapper<T> m, Object... params) { ... }
-    public static int update(DataSource ds, String sql, Object... params) { ... }
+    public static <T> Optional<T> queryOne(Connection conn, String sql, RowMapper<T> m, Object... params) throws SQLException { ... }
+    public static <T> List<T> queryList(Connection conn, String sql, RowMapper<T> m, Object... params) throws SQLException { ... }
+    public static int update(Connection conn, String sql, Object... params) throws SQLException { ... }
 }
 ```
 
+Note the signatures take `Connection`, not `DataSource` — the helper must not open connections either, or it defeats the one-lease-per-operation rule of §3.
+
 - Pure delegation to the try-with-resources pattern above; no reflection, no annotations, no SQL generation. If someone proposes adding criteria builders or entity mapping to it, that's an ORM growing back — reject.
 - The class is named `Jdbc` — a namespace, not `JdbcUtils`/`JdbcHelper`. The banned-suffix ArchUnit rule (see quarkus-hexagonal-core skill) exists precisely to stop this class from becoming a junk drawer.
 - jOOQ (code-gen, type-safe SQL) MAY be evaluated as an alternative via formal ADR; MyBatis/Hibernate remain excluded.
@@ -216,30 +236,40 @@ JDBC blocks. Never run it on the event loop:
 
 ## 8. SQLException translation
 
-One translator in `infrastructure/persistence`, mapping SQLState to domain/persistence exceptions so callers never see `SQLException`:
+`Sql` methods propagate `SQLException`; the `Handler` catches it once, in `execution()`, and translates it through `SqlStateTranslator` (`common/error`) so nothing checked ever escapes `process()` — a checked exception would not trigger the container rollback:
+
+```java
+} catch (SQLException e) {
+    throw SqlStateTranslator.translate("PTY-500-001", e);   // default code if the state is not mapped
+}
+```
 
-| SQLState | Meaning | Throw |
+| SQLState | Meaning | Resulting exception (all unchecked) |
 |---|---|---|
-| `23505` | unique violation | domain conflict exception (→ 409) |
-| `23503` | FK violation | domain integrity exception |
+| `23505` | unique violation | `BusinessException` with the slice's conflict code (→ 409) |
+| `23503` | FK violation | `BusinessException` with the slice's integrity code (→ 409/422) |
 | `40001` / `40P01` | serialization failure / deadlock | retryable `TransientPersistenceException` |
 | `57014` | statement timeout/cancel | `PersistenceTimeoutException` |
 | other | infrastructure failure | `PersistenceException(code, e)` (→ 500) |
 
+Every resulting code is registered in `ErrorCatalog` and present in all locale bundles (see quarkus-error-handling-i18n skill). The client sees a localized message; the `SQLException` stays in the logs.
+
 Set `statement_timeout` (session or per-datasource via `quarkus.datasource.jdbc.additional-jdbc-properties.options=-c statement_timeout=5000`) so runaway queries fail fast instead of holding pool connections.
 
 ## 9. Testing
 
-- Repository tests: `@QuarkusTest` + Dev Services (Testcontainers Postgres starts automatically — no config). Real SQL against real Postgres; never H2 (dialect lies).
+- `<Slice>Sql` tests: `@QuarkusTest` + Dev Services (Testcontainers Postgres starts automatically — no config). Real SQL against real Postgres; never H2 (dialect lies). Obtain a `Connection` in the test and pass it in, exactly as the `Handler` does.
+- `<Slice>Handler` tests are pure Mockito with a mocked `Sql` — no database (see quarkus-hexagonal-core skill).
 - Flyway migrations run at test start (`quarkus.flyway.migrate-at-start=true`) — tests validate DDL and queries together.
 - Native verification: `@QuarkusIntegrationTest` re-runs the same tests against the binary.
 
-## Checklist for a new repository method
+## Checklist for a new `Sql` method
 
-0. Names follow the canonical table above (`Jdbc<Port>` adapter, `<Entity>Repository` port, `UPPER_SNAKE` SQL constants).
-1. SQL text block constant, placeholders only; whitelist for any dynamic fragment.
-2. try-with-resources on connection/statement/resultset (or the `Jdbc` helper).
-3. Transaction boundary on the use case, not here.
-4. `executeUpdate()` count checked; SQLState translated, never leaked.
-5. jsonb via `PGobject`; batch + chunking for bulk; keyset pagination if deep.
-6. `@Blocking`/virtual thread if called from a reactive context; Dev Services test written.
+0. Names follow the canonical table above (`<Slice>Sql` class, imperative method name, `UPPER_SNAKE` SQL constant).
+1. First parameter is `Connection conn`; the method declares `throws SQLException` and opens no connection of its own.
+2. SQL text block constant, schema-qualified, reserved words quoted, placeholders only; whitelist for any dynamic fragment.
+3. try-with-resources on statement/resultset (the caller owns the connection).
+4. No `commit`/`rollback`/`setAutoCommit`; the transaction boundary is `Handler.process()`.
+5. `executeUpdate()` count returned or checked; `SQLException` propagated for the `Handler` to translate, never swallowed.
+6. Generated ids via `RETURNING`; jsonb via `PGobject`; batch + chunking for bulk; keyset pagination if deep.
+7. Rows mapped by hand into the slice's `*Dto`; Dev Services test written.

package/src/commands/dev-all.md

@@ -0,0 +1,105 @@
+---
+description: Batch-run the BMAD dev-story workflow across all pending stories, with per-epic checkpoints and optional commit-per-story.
+argument-hint: "[commit] [skip-review] [checkpoint] [epic=<id>]  e.g. `/dev-all` or `/dev-all commit skip-review` or `/dev-all checkpoint epic=3`"
+allowed-tools: Read, Edit, Write, Bash(git status:*), Bash(git add:*), Bash(git commit:*), Bash(git log:*)
+---
+
+# Batch develop BMAD stories
+
+You are running an **unattended batch** of the BMAD dev-story workflow. Work through
+stories one at a time (preserving per-story context), but do **not** stop for
+confirmation between stories. Only the per-epic checkpoint below is a hard stop.
+
+## The BMAD build cycle — run these EXACT commands per story
+
+For each story, run the DEV agent's three-step cycle, in order:
+
+1. `bmad-create-story`  — create the story file from the epic
+2. `bmad-dev-story`     — implement the story
+3. `bmad-code-review`   — quality validation
+
+Invoke these real BMAD workflows — do NOT improvise your own create/implement/review
+steps. They carry the architecture context and dev-notes inheritance that keep output
+coherent.
+
+> **Note on "fresh chats":** BMAD's docs say to repeat this cycle *in a fresh chat per
+> story*, so each story gets a clean context window. This batch command runs multiple
+> stories in one session, which sacrifices that guarantee for hands-off throughput.
+> That's an acceptable trade for a small/well-understood epic. For a large epic, prefer
+> running the cycle manually per story, or use the per-epic checkpoint below to resume
+> each epic in a fresh session.
+
+- **State file:** `sprint-status.yaml` (source of truth for story status)
+- **Epic definitions:** `epics.md`
+
+## Arguments
+
+Parse `$ARGUMENTS`:
+- `commit`  → enable **commit-per-story** (off by default). When enabled, after a
+  story passes review, run `git add -A && git commit` with a message like
+  `feat(<epic>): <story-id> <short title>`.
+- `epic=<id>` → restrict the batch to a single epic.
+- `checkpoint` → **pause** for confirmation at each epic boundary (off by default —
+  by default the run is fully unattended and does NOT stop between epics).
+- `skip-review` → skip the `bmad-code-review` step. The per-story cycle becomes
+  `bmad-create-story` → `bmad-dev-story` only.
+
+**Default (no `epic=` given): process ALL epics**, in order, running every not-done
+story across the whole project **without stopping between epics**. So bare `/dev-all`
+develops everything unattended; `/dev-all epic=2` develops only epic 2; add
+`checkpoint` if you want a pause + summary before each new epic.
+
+## Loop
+
+1. **Read `sprint-status.yaml`.** Build the ordered list of stories whose status is
+   NOT `done` (e.g. `pending`, `ready`, `in-progress`, `blocked` should be surfaced —
+   see step 6 for blocked). Respect the `epic=` filter if present.
+
+2. **If the list is empty**, report "All stories already done" and stop.
+
+3. **For each story, in order:**
+   a. Announce which story you're starting (id + title).
+   b. Run the BMAD cycle for that story, in order:
+      `bmad-create-story` → `bmad-dev-story` → `bmad-code-review`.
+      **If `skip-review` is set, omit `bmad-code-review`** (run create → dev only).
+   c. If review passed (or `skip-review` is set and implementation completed without
+      error), set that story's status to `done` in `sprint-status.yaml`.
+   d. **If commit-per-story is enabled**, stage and commit (see Arguments). Keep each
+      commit scoped to that one story so a bad story can be rolled back in isolation.
+   e. Continue to the next story WITHOUT asking for confirmation.
+
+4. **Per-epic boundary.** When you finish the last story of an epic and more epics
+   remain, post a short summary: epic name, stories completed/blocked, tests added,
+   files touched, and anything that looked off (scope creep, tests worked around,
+   architectural surprises).
+   - **Default: do NOT stop.** Print the summary and immediately continue into the
+     next epic without asking for confirmation.
+   - **Only if `checkpoint` is set:** stop after the summary and wait for my go-ahead
+     before starting the next epic.
+
+5. **Context hygiene on long runs.** If you notice your context getting large mid-run,
+   say so in the nearest epic-boundary summary and recommend I resume the remaining
+   epics in a fresh session. Don't silently push through degraded context. (This is the
+   main risk of a fully unattended all-epics run — flag it rather than hide it.)
+
+6. **Error / blocked handling.** If a story fails `bmad-code-review` twice, or you hit an error you
+   can't resolve, or a dependency is missing:
+   - Set its status to `blocked` in `sprint-status.yaml` with a one-line reason.
+   - Do NOT mark it `done`. Do NOT keep retrying indefinitely.
+   - Skip it and continue with the remaining stories, then report all blocked stories
+     in the next checkpoint / final summary.
+
+## Final summary
+
+When every eligible story is `done` or `blocked`, stop and report:
+- Count done vs. blocked, grouped by epic
+- List of blocked stories with reasons
+- Commits made (if commit-per-story was on)
+- Any follow-ups I should handle manually
+
+## Guardrails
+
+- Never mark a story `done` unless its review actually passed.
+- Never force-push or rewrite history. Commits only, and only when `commit` is set.
+- If `sprint-status.yaml` and `epics.md` disagree about which stories exist, trust
+  `sprint-status.yaml` for status but flag the mismatch in the summary.

package/src/commands/quarkus-all.md

@@ -0,0 +1,156 @@
+---
+description: Batch-build BMAD stories through Marcus (bmad-quarkus-build) — one skill invocation per story instead of the create-story/dev-story/code-review cycle.
+argument-hint: "[commit] [checkpoint] [review] [force] [dry-run] [epic=<id>] [limit=<n>]  e.g. `/quarkus-all` or `/quarkus-all commit epic=20` or `/quarkus-all dry-run`"
+allowed-tools: Read, Edit, Write, Bash(git status:*), Bash(git add:*), Bash(git commit:*), Bash(git log:*), Bash(git diff:*), Bash(./mvnw:*), Bash(mvn:*)
+---
+
+# Batch build BMAD stories with the Quarkus agent
+
+You are running an **unattended batch** of Quarkus story implementation. Work through
+stories one at a time (preserving per-story context), but do **not** stop for
+confirmation between stories. Only the per-epic checkpoint below is a hard stop.
+
+## The cycle — ONE command per story
+
+For each story, invoke exactly **one** skill:
+
+```
+bmad-quarkus-build   →  "Marcus, implement story <story-key>"
+```
+
+That is the whole per-story cycle. **Do NOT run `bmad-create-story`, `bmad-dev-story`,
+or `bmad-code-review` as separate steps** — Marcus owns the full loop (story
+preparation → red-green-refactor implementation → self-review against the ACs) and
+routes into `bmad-build` plus whichever of the 7 Quarkus domain standards the story
+touches (`quarkus-hexagonal-core`, `quarkus-sql-jdbc-agroal`,
+`quarkus-error-handling-i18n`, `quarkus-openapi-tmforum`, `quarkus-grpc-services`,
+`quarkus-kafka-messaging`, `quarkus-observability-otel`). Splitting the cycle back into
+three commands loses that routing and the native-image/hexagonal review that comes with it.
+
+Pass the story key in the invocation so Marcus dispatches directly instead of rendering
+his menu (his activation Step 8 skips the menu when the intent is already named).
+
+Marcus stays active across stories once activated — do not re-run his activation
+greeting for every story, just hand him the next story key.
+
+- **State file:** `_bmad-output/implementation-artifacts/sprint-status.yaml` (source of truth for story status)
+- **Story files:** `_bmad-output/implementation-artifacts/<story-key>.md`
+- **Epic definitions:** `governance/_bmad-output/planning-artifacts/epics.md`
+
+> **Note on "fresh chats":** BMAD's docs say to repeat the build cycle *in a fresh chat
+> per story*, so each story gets a clean context window. This batch command runs multiple
+> stories in one session, which sacrifices that guarantee for hands-off throughput. That's
+> an acceptable trade for a small/well-understood epic. For a large epic, prefer running
+> `bmad-quarkus-build` manually per story, or use the per-epic checkpoint below to resume
+> each epic in a fresh session.
+
+## Arguments
+
+Parse `$ARGUMENTS`:
+- `commit` → enable **commit-per-story** (off by default). After a story passes, run
+  `git add -A && git commit` with a message like `feat(epic-20): 20-1 create a digital identity`.
+- `epic=<id>` → restrict the batch to a single epic (`epic=20`, `epic=256`).
+- `limit=<n>` → stop after `n` stories have been completed this run.
+- `checkpoint` → **pause** for confirmation at each epic boundary (off by default — by
+  default the run is fully unattended and does NOT stop between epics).
+- `review` → add a separate `bmad-code-review` pass **after** Marcus finishes each story.
+  Off by default: Marcus already reviews his own output, and this is the one case where a
+  second command per story is intentional (fresh-context adversarial review).
+- `force` → override the build-eligibility gate below. Requires that I said so explicitly;
+  never infer it.
+- `dry-run` → print the ordered story list, the eligibility verdict per epic, and stop.
+  Change nothing. Use this first on any wide run.
+
+**Default (no `epic=` given): process all *build-eligible* epics**, in order, running every
+not-done story **without stopping between epics**.
+
+## Build eligibility — read this BEFORE touching any story
+
+`sprint-status.yaml` carries BUILD-STATUS markers as trailing comments on epic headings.
+**They are not statuses.** A `backlog` status on a marked epic means NOT STARTED — it does
+**not** mean cleared to start.
+
+- `[V1]` → **build-ready.** Epics 20, 21, 22, 23, 24, 26, 28, 30, 31.
+- `[BUILD-PROHIBITED]` → **skip.** Epics 32, 33, 34, 35, 36 (36 also reassigned to BC-05).
+  Feature files exist, but building is forbidden — ADR-024 requires a P2→P10 re-run, never
+  a local fix.
+- `[BUILD-PROHIBITED in part]` → **skip epic 27** unless I name a specific permitted story.
+- `[UNCLASSIFIED]` → **skip.** Epics 25, 29, 37–45, 262, 263. Per OI-50 the build decision
+  belongs to the Product Owner + Architect Lead, not to us.
+- `[BLOCKED]` → **skip.** Epics 256, 263.
+
+Re-read the markers from the file rather than trusting this list — the file is the source of
+truth and its scope can change. If `epic=<id>` names a non-eligible epic, refuse and say
+which marker blocks it; only `force` overrides, and even then print the marker you are
+overriding.
+
+The whole file is scoped to **BC-01 only** (29 of the 263 epics in `epics.md`). The other
+epics are absent by design — never treat their absence as done or as something to go build.
+
+## Loop
+
+1. **Read `sprint-status.yaml`.** Build the ordered list of stories whose status is NOT
+   `done`. Legal story statuses in this file are `backlog`, `ready-for-dev`, `in-progress`,
+   `review`, `done`. Apply the eligibility gate, then the `epic=` filter, then `limit=`.
+
+2. **If the list is empty**, report "No eligible stories pending" and stop.
+
+3. **For each story, in order:**
+   a. Announce which story you're starting (key + title + epic).
+   b. Invoke `bmad-quarkus-build` with that story key. One invocation. Nothing else.
+   c. If `review` is set, run `bmad-code-review` on the resulting diff.
+   d. On success — ACs met, tests written test-first and passing — set the story's status to
+      `done` in `sprint-status.yaml` and update `last_updated`.
+   e. If it's the epic's last story and all its stories are now `done`, set `epic-<id>: done`.
+      Set `epic-<id>: in-progress` when starting the epic's first story.
+   f. **If commit-per-story is enabled**, stage and commit. Keep each commit scoped to that
+      one story so a bad story can be rolled back in isolation.
+   g. Continue to the next story WITHOUT asking for confirmation.
+
+4. **Per-epic boundary.** When you finish the last story of an epic and more epics remain,
+   post a short summary: epic, stories completed/held, tests added, files touched, and
+   anything that looked off (scope creep, tests worked around, hexagonal or native-image
+   surprises, a domain standard that contradicted the story).
+   - **Default: do NOT stop.** Print the summary and continue into the next epic.
+   - **Only if `checkpoint` is set:** stop after the summary and wait for my go-ahead.
+
+5. **Context hygiene on long runs.** If your context is getting large mid-run, say so in the
+   nearest epic-boundary summary and recommend resuming the remaining epics in a fresh
+   session. Don't silently push through degraded context — that's the main risk of a fully
+   unattended all-epics run.
+
+6. **Error / held handling.** If Marcus can't complete a story, a second attempt fails, or a
+   dependency is missing:
+   - **Do not invent a `blocked` status** — this file's state machine has no such value and
+     the header says so explicitly. Leave the story at its current status and append a
+     trailing comment on its line: `# HELD 2026-xx-xx: <one-line reason>`.
+   - Do NOT mark it `done`. Do NOT retry indefinitely (two attempts max).
+   - Skip it and continue, then report all held stories in the next checkpoint / final summary.
+
+## Final summary
+
+When every eligible story is `done` or held, stop and report:
+- Count done vs. held, grouped by epic
+- Held stories with reasons
+- Epics skipped by the eligibility gate, with the marker that skipped them
+- Commits made (if `commit` was on)
+- Any follow-ups I should handle manually
+
+## Guardrails
+
+- **One `bmad-quarkus-build` invocation per story.** Never decompose it back into
+  `bmad-create-story` → `bmad-dev-story` → `bmad-code-review`.
+- Never mark a story `done` unless its tests actually pass and every AC is met. ACs in these
+  stories are verbatim Gherkin — do not edit, reword, or renumber them.
+- Never start a story in a `[BUILD-PROHIBITED]`, `[BUILD-PROHIBITED in part]`,
+  `[UNCLASSIFIED]`, or `[BLOCKED]` epic without explicit `force`.
+- FR-1243 forbids marking anything Done while a blocker is in scope, and the 2026-08-13
+  readiness report reads NEEDS WORK. This command asserts no gate verdict and closes no open
+  item — it only advances story statuses it actually completed.
+- Never force-push or rewrite history. Commits only, and only when `commit` is set.
+- `sprint-status.yaml` has a stale `story_location:` pointing at a macOS path
+  (`/Users/diego/...`). Trust the real repo path `_bmad-output/implementation-artifacts`;
+  flag the mismatch in the final summary rather than editing it mid-run.
+- If `sprint-status.yaml` and `epics.md` disagree about which stories exist, trust
+  `sprint-status.yaml` for status and flag the mismatch. Declared-vs-actual epic count gaps
+  (the file notes one) are a PM finding — report, don't reconcile.