git:20260911.f7fbe1a to git:20260916.d4ab12d

+ description: Orchestrates the feature pipeline — one use case per run, 5 design skills → spec.md for the executor

+ argument-hint: "<feature description> | UC-NNN-slug | empty to list"

+ **Manual only.** `disable-model-invocation: true` hides this skill from the model: the

+ `Skill` tool can't call it, and trying is blocked. When a conversation reaches the point

+ of running it, print the exact command for the user to type — don't attempt the call.

+

+ **Ownership:** Feature zero→spec orchestrator. Owns the sequence, the input table, the

+ spec lifecycle (`status:`), and the final output (`UC-NNN-spec.md`). Does **not** own the

+ use case number or slug — `use-case-design` does.

+ - `docs/use-cases/UC-*/` — folder existence and each spec's `status:` line, by command

+ - `docs/use-cases/UC-NNN-<slug>/*.md` — the partials of the case being run

+ - `docs/use-cases/UC-NNN-<slug>/00-caso-de-uso.md` and `docs/use-cases/BACKLOG.md` — via

+ `use-case-design`

+ - `docs/use-cases/UC-NNN-<slug>/20-persistencia.md` — via `persistence-architect`,

+ migration SQL included as a code block, never as a file under `src/`

+ - `docs/use-cases/UC-NNN-<slug>/UC-NNN-spec.md` — implementation plan (executor-ready),

+ including its `status:` line (`draft` → `approved`)

+ **Never writes under `src/`.** Neither does any skill it chains. Every file under `src/`

+ — migrations included — belongs to `java-spring-boot-developer`.

+

+ **Never runs `git add`, `git commit`, or `git push`.** Neither does any skill it chains.

+ Git happens only through `git-publish`, behind its two confirmations, at the end steps

+ below. No end of this flow is left without an explicit git instruction.

+

+ 1. `use-case-design` — invoked for a new case; skipped on resume when `00-caso-de-uso.md` exists

+ 7. `java-spring-boot-developer` — offered, only for an `approved` spec

+ 8. `git-publish` — invoked at the end, per § End of flow

+ invokes it. Its catalog travels preloaded inside `java-spring-boot-developer` and gets

+ applied there, directly, when a symptom already in the generated code matches a row —

+ `@.claude/decisions/0025-java-patterns-preloaded-in-executor.md`.

+ ## Spec lifecycle

+

+ `UC-NNN-spec.md` opens with a frontmatter carrying one field:

+

+ | `status:` | Written by | When |

+ |---|---|---|

+ | `draft` | this skill | at consolidation |

+ | `approved` | this skill | only after the user's explicit approval, § End of flow |

+ | `implemented` | `java-spring-boot-developer` | with a green build |

+

+ A use case folder is **open** when it has no `UC-NNN-spec.md` yet, or its spec is `draft`.

+

+ **One `/new-feature` produces one use case.** The next one only starts once the previous

+ is `approved` or `implemented`.

+

+ **An approved spec is immutable.** Later cases read approved specs as a read-only

+ contract and reuse the aggregate already modeled. A change a new case needs in an

+ approved one goes into the `## Impact on approved use cases` section of the **new**

+ spec; the executor applies it in code. Don't edit the old spec.

+

+ Decide what the current case needs. Don't defer or anticipate a decision "for the future

+ case" — the future case decides it, in its own impact section.

+

+ ---

+

+ Runs before any skill invocation, any write, and any question. Every check is a command;

+ the model doesn't interpret the input.

+ ### 1 · Input table — closed

+ Survey the use cases once:

+ ```bash

+ find docs/use-cases -mindepth 1 -maxdepth 1 -type d -name 'UC-*' 2>/dev/null | sort | while read -r d; do s=$(find "$d" -maxdepth 1 -name 'UC-*-spec.md' -exec grep -m1 '^status:' {} \;); echo "$d ${s:-status: (no spec)}"; done

+ ```

+ Classify the argument with the argument in single quotes:

+

+ ```bash

+ printf '%s' '<argument>' | grep -Eqx 'UC-[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*' && echo EXACT

+ printf '%s' '<argument>' | grep -Eiq 'uc-[0-9]' && echo UC_LIKE

+ test -d 'docs/use-cases/<argument>' && echo FOLDER

+ ```

+

+ Evaluate in order and **stop at the first row that matches**. There is no "any other

+ text" row.

+

+ | # | Input | Result |

+ |---|---|---|

+ | 1 | empty | ✅ list the survey above — each case with its `status` — and stop |

+ | 2 | `EXACT`, `FOLDER`, status `draft` or `(no spec)` | ✅ resume: skip `use-case-design`, generate only the missing partials, then consolidation |

+ | 3 | `EXACT`, `FOLDER`, status `approved` or `implemented` | ❌ `approved spec is immutable — describe the change as a new feature` |

+ | 4 | `EXACT`, no `FOLDER` | ❌ `use case not found; to create one, describe the feature` |

+ | 5 | `UC_LIKE` but not `EXACT` (slug plus context, malformed slug, two slugs, a path) | ❌ `ambiguous argument` |

+ | 6 | free text, and the survey shows an open case | ❌ `<UC folder> is open — resume or approve it first` |

+ | 7 | free text, and no open case | ✅ new: pass the description **as is** to `use-case-design` |

+ | — | anything else | ❌ `unrecognized argument` |

+

+ **The model doesn't interpret the input.** It doesn't fix a slug, separate a slug from

+ context, or infer intent. A text that almost matches a row doesn't match it.

+

+ **An error has a fixed shape and ends the run.** After it: no skill call, no write, no

+ question.

+

+ ```text

+ ❌ /new-feature: <reason>.

+ Usage: /new-feature <feature description> → new use case

+ /new-feature UC-NNN-slug → resume a draft case

+ /new-feature → list

+ ```

+

+ ### 2 · Worktree — decided here, never later

+

+ ```bash

+ git rev-parse --show-toplevel

+ git rev-parse --git-dir --git-common-dir

+ ```

+

+ Both fail → not a git repository yet: no worktree, paths are relative to the project

+ root. Different `--git-dir` and `--git-common-dir` → the session is inside a worktree. Every

+ path this run writes is under `--show-toplevel`, and nothing is written in the main

+ checkout. If the work should be isolated in a worktree and isn't yet, that is decided

+ **now**, before any question or write. Never enter or leave a worktree mid-flow — edits

+ get refused outside it and orphan folders appear in the main checkout.

+

+ ### 3 · Project

+

+ Checks `pom.xml` (exists + parseable), `.claude/forbidden-imports.txt`, and that a domain

+ package exists. **Discover it, don't assume it.**

+

+ ```bash

+ find src/main/java -type d -name domain

+ ```

+

+ `src/domain/` and `adapter/` don't exist in any blueprint: they're Maven module paths,

+ and even in multi-module blueprints the layer lives at `<module>/src/main/java/…`. A

+ guardrail that checks a literal path either fails on a valid project or passes by

+ accident — neither case guards anything. The package name comes from the active

+ blueprint's `packages.map`; where the blueprint isn't at hand, it comes from the `find`

+ above.

+

+ ### 4 · Disk

+

+ Available space > 100MB, write permission on `docs/use-cases/`.

+

+ ### Step 1: Use case (new case only)

+ **Invoke** `use-case-design` via the Skill tool, with the user's description as is.

+ `use-case-design` owns the boundary, the number, and the slug. When the description

+ holds several use cases, it asks the user which one to design, designs that one, and

+ writes the rest to `docs/use-cases/BACKLOG.md`. This run continues with the one it

+ created — never with the others.

+ **Output:** `docs/use-cases/UC-NNN-<slug>/00-caso-de-uso.md` — its folder name is the

+ `UC-NNN-<slug>` every later step uses.

+ 2. Consolidate into a single file: `UC-NNN-spec.md`, with `status: draft`

+ - `## Impact on approved use cases`: carried from `00-caso-de-uso.md` — "none" when empty

+ ---

+ ## End of flow

+

+ Every branch below ends in an explicit instruction. None of them runs git outside

+ `git-publish`.

+

+ ### Approval — always asked

+

+ `AskUserQuestion`: **Approve `UC-NNN-spec.md`** / **Keep as draft**.

+

+ - **Keep as draft** → report the spec path and the resume command

+ (`/new-feature UC-NNN-<slug>`), and stop. No git: a draft isn't a deliverable.

+ - **Approve** → change the spec's line to `status: approved`, then the executor offer.

+

+ ### Executor offer — always asked, only for `approved`

+

+ `AskUserQuestion`: **Implement now** (`java-spring-boot-developer`) / **Not now**.

+

+ - **Implement now** → delegate to `java-spring-boot-developer`, sending the spec path.

+ - **Success** (final summary reports the checklist complete, the build green, and the

+ spec at `status: implemented`) → **invoke** `git-publish` via the `Skill` tool, with

+ `feat(UC-NNN-<slug>): <one-line summary>` as context.

+ - **Failure** → report the executor's failure and stop. No git.

+ - **Not now** → **invoke** `git-publish` via the `Skill` tool, with context

+ `docs(UC-NNN-<slug>): approved spec` and the paths `docs/use-cases/UC-NNN-<slug>/` and

+ `docs/use-cases/BACKLOG.md` as the only paths to stage.

+

+ `git-publish`'s two confirmation gates decide whether anything is committed or pushed —

+ this orchestrator only triggers the offer.

+

+ ### Final report

+

+ Last message of the run, and the only report: the spec path and status, the backlog

+ entries left for later (if any), what `git-publish` did, and a recommendation to run

+ `/clear` before the next `/new-feature` — a clean context per use case keeps cost

+ measurable per case.

+

+ - Frontmatter: `status:`

+ - Impact on approved use cases ("none" when empty)

+ - **`@.claude/decisions/0037-lessons-learned-005-remediation.md`** — closed input table,

+ one use case per run, spec lifecycle, no `src/` and no git outside `git-publish`.

+ - **Invariant 2** (`@CLAUDE.md`) — single owner. The orchestrator owns `UC-NNN-spec.md`;

+ `use-case-design` owns number and slug.

+ Step 6.7 copies skills. `/new-feature` travels the same way — the user runs

+ `/new-feature <feature description>` to design a new feature.