vinta-ai-workflows 0.7.0-alpha23 → 0.7.0-alpha24

package/CHANGELOG.md

@@ -30,6 +30,93 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **Agents stop for input with clickable questions instead of prose.** When a
+  skill or a sub-agent needs a decision from you, it now asks through your
+  harness's structured question tool, so you get the options as buttons plus
+  a free-text field, rather than a question buried at the end of a long
+  report. The tools are Claude Code's `AskUserQuestion`, OpenCode's
+  `question`, Codex's `request_user_input`, Cursor's `AskQuestion`, VS Code
+  Copilot's `askQuestions` and Gemini CLI's `ask_user`.
+  - **`AGENTS.md` gains an "Asking the human" section.** Its canonical text is
+    in [`vinta-write-agents-md/resources/asking-the-human.md`](skills/vinta-write-agents-md/resources/asking-the-human.md),
+    which `vinta-write-agents-md` copies verbatim between
+    `asking-the-human:start/end` markers. The section maps the tool name per
+    harness and sets the question shape. Every question has 2–4 concrete
+    options with descriptions, the recommended one first and marked
+    ` (Recommended)`, and no "Other" option. Questions are batched up to 4 per
+    call (3 on Codex). Open-ended questions still offer the candidates the
+    agent found. Confirmation gates are questions, never "reply go". It also
+    gives the fallback when no tool is available.
+  - **Sub-agents return `status: NEEDS_INPUT`.** Claude Code and Codex do not
+    let a sub-agent call the question tool. A phase agent that hits a decision
+    it should not make alone now stops at a clean point and returns a
+    `questions:` block in the tool's own shape. The new
+    `plan-execution/partials/relay-questions.md` is included by
+    `implement-phase`, `review-phase` and `amend-plan`. It turns that block
+    into an `AskUserQuestion` call, records the answer in tracking, and
+    continues the same agent. `implementer-prompt.md#NEEDS_INPUT` carries the
+    contract into every composed implementer prompt, and
+    `vinta-derive-subagents` puts it in every read-write agent body. The
+    dependency-license block, which used to tell a sub-agent to "ask via
+    `AskUserQuestion`", now returns `NEEDS_INPUT`.
+  - **Prose stop points became option questions** across the plan-execution
+    unit, the foundation skills and the bootstrap skills. Examples:
+    - choosing the plan file;
+    - the start-run gate, which replaces "wait for go";
+    - the Tier-4 failure: amend the plan, retry with guidance, skip the
+      phase, or stop;
+    - resuming a run;
+    - a missing worktree;
+    - graph and crew validation;
+    - wave-merge conflicts;
+    - rebase failures, co-authored branches and merged phases in `amend-plan`;
+    - review findings that need a human decision;
+    - migration failures in `prepare-worktree`;
+    - mismatches when `handoff` resumes;
+    - the three-failed-attempts stop and MCP preflight failures in
+      `systematic-debugging`;
+    - the unclear-file, date and sidecar questions in
+      `vinta-migrate-plans-specs`.
+  - **Consumers:** `vinta-sync-ai-tools` adds a one-time migration. It
+    appends the section to an existing `AGENTS.md`, adds the needs-input
+    contract to read-write agent YAMLs, and re-renders the affected skills
+    together.
+- **`vinta-ai-maestro` shows an agent's questions as a card you click.**
+  - **Detection.** The scheduler reads every agent turn as it drains
+    (`src/questions`). It takes a `NEEDS_INPUT` block in the agent's last
+    message, or a question tool call (`AskUserQuestion` / `question` /
+    `request_user_input`) that was its last act. Either one parks the node on
+    a new `kind: 'agent'` question.
+  - **The card.** It shows each option as a button with its description, and
+    marks the recommended one. The last choice is always **Other**, which
+    holds a free-text field. On a single-choice question it is exclusive:
+    typing in it deselects the picked option, and picking an option deselects
+    it. The daemon applies the same rule to an API answer. A single single-choice question
+    answers on the click. Several questions run as a wizard: one step per
+    question, with picking an option moving on and number keys to pick, then
+    a review step and Send.
+  - **The answer resumes the agent's own session.** The turn's effect returns
+    only once the agent stops asking. Under `--retry-after`, an unanswered
+    question takes the recommended options and is journalled as `unattended`.
+  - **§11 still holds.** The questions are written to the transcript as an
+    `agent_question` entry. The journal row carries a fixed sentence and the
+    effect id, and the answer is journalled as option indices plus the
+    operator's words.
+  - **API.** `POST …/answer` accepts `answers` (one
+    `{ selected, text? }` per question) as well as the scalar `answer`.
+    `NodeDetail.question` gains `ask`. The implementer prompt now teaches the
+    `NEEDS_INPUT` block. `MockAdapter` takes `scripts`, one per session.
+
+
+- **The run view's token, cost and cache figures explain themselves.** Each
+  row in *Sessions and cost* now has an info icon. Hover over it for a quick
+  look, or click to keep it open. It says where the figure comes from and
+  shows the exact counts it was summed from. Token totals are summed from what
+  each harness reports when a session ends. Fresh input is shown apart from
+  cached input. Cost is the harness's own estimate at API list prices, not
+  your bill on a subscription plan. Codex sessions report no cost. Sessions
+  still running are not counted yet. `vinta-design-system` gains a `popover`
+  component.
 - **PR Review Canvas integration (`integrations.pr-review-canvas`).** The
   bootstrap now offers [PR Review Canvas](https://github.com/vintasoftware/pr-review-canvas)
   as its first *integration*: an external tool that installs its own skill.
@@ -207,6 +294,55 @@ the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Changed
 
+- **Maestro: the node view's right-hand column stays short.** Gate logs open
+  in a dialog instead of an inline accordion. The dialog opens at the end of
+  the log, keeps up with a running gate's output, numbers the lines, and has
+  ← / → to switch gates and a copy button. The question card's gate reference
+  opens the same dialog. Agent sessions are now a timeline with the newest
+  turn first, showing the latest five. The turn that is currently running
+  pulses and counts up. The full history opens in a dialog. The Changes card
+  lists five files instead of ten.
+
+- **`vinta-ai-maestro` node view: steering is a chat input, and every control
+  says what it does.** The separate Steering card is gone. Its message box now
+  sits at the bottom of the Transcript panel and follows it to full page. Add
+  context and Redirect are a toggle over one Send button, which also sends on
+  Ctrl/⌘+Enter. The sentence under the box says what will happen for this
+  node's status and harness before you press it. Pause, Take over, Abort and
+  Retry phase moved to the page header beside the node's status, and only the
+  ones that apply are shown. Abort now asks for confirmation. A new **How
+  steering works** panel documents each control: when it is available, what
+  happens in practice, how to undo it, and what the node's harness supports.
+
+- **Worktrees now get their own copy of the dependency dirs, never a
+  symlink.** A symlinked `node_modules` / `vendor/` / `venv/` sent writes
+  back into the main checkout, because tools resolve real paths: bundler and
+  test-runner caches, `postinstall` output and installs all landed there.
+  Parallel worktrees then raced on that one tree, and the filesystem sandbox
+  blocked those writes in the middle of a run.
+  - **`prepare-worktree`** copies every dep dir with a copy-on-write clone
+    (`cp -ac` on macOS, `cp -a --reflink=auto` on Linux). On APFS, btrfs and
+    XFS that is close to free on disk. It reinstalls virtualenvs and yarn PnP
+    instead, because their trees store absolute paths into the main checkout.
+    When the plan adds deps, it runs an install on top of the copy. In a
+    workspace it copies every member's `node_modules/`, not only the root's.
+    The summary's `state.deps.strategy` is now `copy | reinstall`.
+  - **Config:** `skills.prepare-worktree.deps_strategy` now defaults to
+    `copy`, where it used to default to `symlink`. `symlink` stays in the
+    schema enum so existing configs still validate, but it is deprecated and
+    read as `copy`. The bootstrap interview no longer offers it.
+  - **Maestro:** `LanePool` copies (clones) the main checkout's
+    `node_modules` into each lane instead of linking it. The lane summary
+    records `deps.strategy: copy`. A lane keeps its own tree across recycles,
+    so a project whose phases change deps should run its install in
+    `setup_cmd`. If the main checkout's `node_modules` is itself a link, the
+    lane gets the same link (a junction on Windows). When a resumed lane still
+    holds a link from an older version, that link is replaced with a copy.
+  - **Consumers:** re-sync to pick up the new `prepare-worktree` body. To
+    stop the interview default from being re-emitted, change
+    `deps_strategy: symlink` to `copy` (or `reinstall`) in
+    `.vinta-ai-workflows.yaml`. Worktrees that already exist keep their links
+    until they are re-provisioned.
 - **`plan-feature` AI model tiers pick up the late-September releases.**
   `plan-feature/resources/ai-models.yaml` now cites `claude-sonnet-5-5`
   (tier 2, was `claude-sonnet-5`) and `gpt-6.1-sol` (tier 3, was

package/README.md

@@ -224,7 +224,7 @@ The 0.2.0 alpha line adds five foundation skills and restructures plan execution
 
 - **`handoff` (always)** — writes a session-continuation doc to `.vinta-ai-workflows/handoffs/` so a fresh session, a different agent, or a teammate can resume in-flight work without re-deriving context. Write mode gathers the goal, what's verified vs. still assumed, decisions and the alternatives rejected, landmines, and the single concrete next step **from the repo, never from memory**. Resume mode reads a handoff and re-checks its claims against the repo before trusting them.
 - **`deslop-comments` (always)** — rewrites the comments and doc blocks a task touched into Simple English, stripping AI-slop vocabulary and negative framing. Comment-only: no renames, no behavior change. It's wired into the review flow — `review-phase` Layer 2 gained a comment-hygiene check and dispatches a `fixer` to run this skill on any comment-slop finding — and is also invokable standalone ("deslop these comments").
-- **`prepare-worktree` (opt-in)** — provisions a fully-runnable git worktree for parallel plan work so a long-running plan can build, test, migrate, and hit databases without disturbing the main checkout. It reads the plan plus `.gitignore` / manifests / env / docker config and decides per ignored path whether to symlink, copy, or fork (dev DB, env files, compose project name). It also ships an OS-level write-guard — `sandbox-run.sh` (`sandbox-exec` / `bwrap`) for subprocess runtimes and a `PreToolUse` hook for Claude Code's in-process subagents — so a stray write back to the main checkout fails at the kernel layer instead of relying on a cooperative "stay in the worktree" instruction. `implement-plan` Step 0 question (c) opts a run into it, and parallel phase execution requires it — one lane per concurrent phase.
+- **`prepare-worktree` (opt-in)** — provisions a fully-runnable git worktree for parallel plan work so a long-running plan can build, test, migrate, and hit databases without disturbing the main checkout. It reads the plan plus `.gitignore` / manifests / env / docker config and gives every worktree its own copy of the dependency dirs (never a symlink) and decides per remaining ignored path whether to copy, fork, or share (dev DB, env files, compose project name). It also ships an OS-level write-guard — `sandbox-run.sh` (`sandbox-exec` / `bwrap`) for subprocess runtimes and a `PreToolUse` hook for Claude Code's in-process subagents — so a stray write back to the main checkout fails at the kernel layer instead of relying on a cooperative "stay in the worktree" instruction. `implement-plan` Step 0 question (c) opts a run into it, and parallel phase execution requires it — one lane per concurrent phase.
 - **`thermo-nuclear-code-quality-review` (opt-in)** — a deliberately harsh, on-demand structural-maintainability audit of a diff (abstraction quality, giant files, spaghetti-condition growth) that hunts for "code-judo" reframes collapsing whole branches / helpers / modes / layers rather than polishing them. Read-only — it reports findings and hands each fix to a `fixer`. `review-phase` Layer 3 now applies a condensed version of this lens on every phase and escalates to the full audit only when a phase touches core architecture, crosses ~1,000 lines, or surfaces a structural smell too big to fix inline.
 - **`handoff-to-client` (opt-in, API-only repos)** — generates a self-contained markdown document for the client teams consuming the repo's API: every endpoint / operation added, changed, deprecated, or removed on the current branch vs. the default branch, with request/response shapes derived from the code, auth + error changes, breaking-change flags judged from the strictest plausible client, one realistic example per operation, and per-platform migration notes. Template-rendered from `skills.handoff-to-client.*` config (required `client_platforms`, plus `api_style` / `api_spec_path` / `output_dir`).
 
@@ -252,7 +252,7 @@ Land at `ai-tools/skills/<name>/SKILL.md`. Always-on unless flagged optional.
 | `add-e2e-test` | **opt-in** | Add an e2e test. Body covers e2e framework, page-object pattern, auth/storage-state, seed helpers, tenant scoping, screenshot conventions. |
 | `add-env-var` | **opt-in** | Propagate a new env var through every layer (`.env.example`, build tool envPrefix, build cache hash, app config, AGENTS.md, CI, deploy injection). |
 | [`add-one-off-script`](skills/vinta-derive-skills/resources/foundation-skills/add-one-off-script/SKILL.md) | **opt-in** | Author one-off operational scripts (backfills, cleanups, ad-hoc fixes). Ships a `BaseOneOffScript` class (Python + TS) enforcing dry-run default, idempotency, batched DB ops, segmented CSV backups, signal-safe interruption, multi-sink logging. |
-| [`prepare-worktree`](skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/SKILL.md) | **opt-in** | Provision a fully-runnable git worktree for parallel plan work — reads the plan + `.gitignore` + manifests + env / docker config and decides per ignored path whether to **symlink / copy / fork** (dev DB, env files, compose project name). Ships an OS-level write-guard (`sandbox-run.sh` + a Claude Code `PreToolUse` hook) so stray writes to the main checkout fail at the kernel layer. `implement-plan` Step 0 question (c) opts a run into it, and parallel phase execution requires it — one lane per concurrent phase. |
+| [`prepare-worktree`](skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/SKILL.md) | **opt-in** | Provision a fully-runnable git worktree for parallel plan work — reads the plan + `.gitignore` + manifests + env / docker config and gives each worktree its **own dependency copy** (never a symlink) and decides per remaining ignored path whether to **copy / fork / share** (dev DB, env files, compose project name). Ships an OS-level write-guard (`sandbox-run.sh` + a Claude Code `PreToolUse` hook) so stray writes to the main checkout fail at the kernel layer. `implement-plan` Step 0 question (c) opts a run into it, and parallel phase execution requires it — one lane per concurrent phase. |
 | [`thermo-nuclear-code-quality-review`](skills/vinta-derive-skills/resources/foundation-skills/thermo-nuclear-code-quality-review/SKILL.md) | **opt-in** | Deliberately harsh structural-maintainability audit of a diff — abstraction quality, giant files, spaghetti-condition growth — hunting "code-judo" reframes that collapse whole branches / helpers / modes / layers. Read-only; hands each fix to `fixer`. `review-phase` Layer 3 runs a condensed lens every phase and escalates to this full audit on core-architecture / ~1000-line / structurally-smelly phases. |
 | `handoff-to-client` | **opt-in** | (API-only repos) Generate a self-contained API-change handoff doc for the client teams consuming the repo's API — every endpoint / operation added / changed / deprecated / removed vs the default branch, with request/response shapes, auth + error changes, breaking-change flags, one example per operation, and per-platform migration notes. Template-rendered from `skills.handoff-to-client.*` config (client platforms, API style, spec path). |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vinta-ai-workflows",
-  "version": "0.7.0-alpha23",
+  "version": "0.7.0-alpha24",
   "description": "Bootstrap AI tooling (AGENTS.md, skills, sub-agents) across Claude Code, Codex, Cursor, and VS Code + GitHub Copilot.",
   "type": "module",
   "bin": {

package/schemas/vinta-ai-workflows-config.v1.schema.json

@@ -209,7 +209,7 @@
           "enum": ["enabled", "disabled"]
         },
         "prepare-worktree": {
-          "description": "Provision a fully-runnable git worktree for parallel feature work — symlinks dep dirs, copies env files, forks dev / test DBs, namespaces docker-compose project + network, drops a summary YAML for mechanical teardown. Copy-verbatim foundation skill (bucket A). When `enabled`, project-level defaults (worktree root, deps strategy, compose network strategy) live under `skills.prepare-worktree`. Consumed by `implement-plan` when its Step 0 question (c) opts in — the orchestrator runs `prepare-worktree` once at the start of a plan run and threads the worktree path through every subagent's prompt so phases all stack inside the same isolated checkout.",
+          "description": "Provision a fully-runnable git worktree for parallel feature work — gives each worktree its own copy of the dep dirs, copies env files, forks dev / test DBs, namespaces docker-compose project + network, drops a summary YAML for mechanical teardown. Copy-verbatim foundation skill (bucket A). When `enabled`, project-level defaults (worktree root, deps strategy, compose network strategy) live under `skills.prepare-worktree`. Consumed by `implement-plan` when its Step 0 question (c) opts in — the orchestrator runs `prepare-worktree` once at the start of a plan run and threads the worktree path through every subagent's prompt so phases all stack inside the same isolated checkout.",
           "type": "string",
           "enum": ["enabled", "disabled"]
         },
@@ -421,7 +421,7 @@
           }
         },
         "prepare-worktree": {
-          "description": "Configuration for the `prepare-worktree` foundation skill. Optional when `foundation_skills.prepare-worktree` is `enabled` — every field has a sensible default. Consumed by the skill at runtime to bias the per-worktree symlink-vs-copy-vs-fork decisions.",
+          "description": "Configuration for the `prepare-worktree` foundation skill. Optional when `foundation_skills.prepare-worktree` is `enabled` — every field has a sensible default. Consumed by the skill at runtime to bias the per-worktree copy-vs-reinstall-vs-fork decisions.",
           "type": "object",
           "additionalProperties": false,
           "properties": {
@@ -431,10 +431,10 @@
               "minLength": 1
             },
             "deps_strategy": {
-              "description": "Default strategy for dep dirs (`node_modules/`, `vendor/`, `venv/`) when the active plan does NOT install new deps. `symlink` reuses main's install (fast, safe for read-only); `copy` clones it (safe for pnpm-style relative-symlink stores, fails for yarn PnP); `reinstall` runs the package manager fresh in the worktree. The skill flips to `reinstall` automatically when it detects dep churn in the plan body.",
+              "description": "Default strategy for dep dirs (`node_modules/`, `vendor/`, `venv/`). Every worktree owns its dep dirs; they are never symlinked back to the main checkout. `copy` makes a copy-on-write clone of main's install, close to free on disk on APFS / btrfs / XFS; it is safe for pnpm-style relative-link stores and falls back to a plain copy elsewhere. `reinstall` runs the package manager fresh in the worktree. The skill always reinstalls virtualenvs and yarn PnP, because their trees store absolute paths into the main checkout, and it adds an install on top of the copy when the plan adds deps. `symlink` is deprecated and read as `copy`; it stays in the enum only so existing configs keep validating.",
               "type": "string",
-              "enum": ["symlink", "copy", "reinstall"],
-              "default": "symlink"
+              "enum": ["copy", "reinstall", "symlink"],
+              "default": "copy"
             },
             "compose_network": {
               "description": "Default docker-compose networking strategy for the worktree. `per-worktree` spins a fresh isolated network (safest, doubles infra); `shared-external` joins an externally-declared network so the worktree can talk to main's compose services (queues, caches, search); `host` uses host networking when the project already does. Skill writes the chosen strategy into the worktree's `docker-compose.override.yml` (or equivalent) when `compose_change` is set.",

package/skills/vinta-bootstrap-ai-tools/SKILL.md

@@ -26,7 +26,7 @@ This orchestrator runs six sub-skills in order. Each is its own SKILL.md so it c
 5. [vinta-install-ai-tools-setup](../vinta-install-ai-tools-setup/SKILL.md) — copy the canonical `setup-ai-tools.mjs` into `ai-tools/scripts/`, wire the package script alias, run setup, verify all vendor paths resolve. Then install the skills of any enabled integration (D.2) through that tool's own CLI.
 6. [vinta-migrate-plans-specs](../vinta-migrate-plans-specs/SKILL.md) — find any pre-existing implementation plans / feature specs scattered across the repo (`docs/`, `specs/`, `plans/`, root markdown, etc.) and propose moving them to the canonical layout `ai-plans/YYYY-MM-DD-{FEATURE_NAME}_{PLAN|SPEC}.md`. Read-only by default; every rename is gated on per-file user approval. Skipped automatically when the analysis finds no candidates.
 
-Each sub-skill returns a short status report. Don't run the next sub-skill until the previous finished cleanly. If a sub-skill fails or surfaces ambiguity, surface that to the user and resolve before continuing.
+Each sub-skill returns a short status report. Don't run the next sub-skill until the previous finished cleanly. If a sub-skill fails or surfaces ambiguity, resolve it with the user before continuing — as an `AskUserQuestion` with concrete options (e.g. `Retry <sub-skill> (Recommended)`, `Skip it, continue`, `Stop`), never as a prose question at the end of the status report.
 
 ### Sibling skill — `create-qa-use-cases`
 
@@ -47,7 +47,7 @@ If the repo already has an `AGENTS.md` (at the root, or at the legacy `ai-tools/
 
 ## Interview (Step 0 — before any sub-skill runs)
 
-Use `AskUserQuestion` for finite-choice questions; iterate plain prose for open-ended ones. Same convention as [plan-feature](../plan-feature/SKILL.md) and [create-spec](../create-spec/SKILL.md).
+Every question goes through `AskUserQuestion` — the harness's structured question tool, which renders clickable options plus a free-text field. On harnesses other than Claude Code, use the equivalent tool listed in [asking-the-human](../vinta-write-agents-md/resources/asking-the-human.md), and follow its shape rules: 2–4 options, recommended first with ` (Recommended)`, no "Other" option, up to 4 questions per call (3 on Codex). For open-ended questions, offer the candidates the analysis found (detected commands, paths, environments, branch names) as options; the free-text field covers the rest. Plain prose only when there is no candidate at all, one question per message.
 
 ### A. Scope
 
@@ -113,7 +113,7 @@ Seven skills are part of the foundation set but aren't always needed. Ask explic
 
    **Follow-up only when `prepare-worktree` = Yes — worktree defaults.** Three short questions land under `skills.prepare-worktree.*`:
    - **Worktree root.** `AskUserQuestion`: `.claude/worktrees` (claude-code convention; the runtime's `EnterWorktree` puts them there), `../<repo-name>-wt-` (sibling dirs of the main checkout — survives across runtimes; relative-path tooling that walks up still works). Auto-pick the first when claude-code is the only selected vendor; ask when multiple vendors are in the **Scope** group's vendor coverage answer.
-   - **Default deps strategy when the plan does NOT install new deps.** `AskUserQuestion`: `symlink` (fastest, reuses main's `node_modules` / `vendor/` / `venv/`), `copy` (defensive; safe for pnpm + npm + cargo + go; risky for yarn PnP + venv), `reinstall` (slowest, always correct). Recommend `symlink` for pnpm / npm / cargo / go projects; `reinstall` for poetry / yarn PnP.
+   - **Default deps strategy.** Every worktree gets its own dependency dirs and never symlinks main's. `AskUserQuestion`: `copy` (copy-on-write clone of main's `node_modules` / `vendor/` — fast and close to free on disk on APFS / btrfs / XFS; right for npm / pnpm / cargo / go / bundler), `reinstall` (run the package manager fresh in the worktree — slower, but always correct). Recommend `copy`, except `reinstall` for poetry / uv / venv / yarn PnP projects, whose trees store absolute paths into the main checkout. The skill reinstalls virtualenvs and yarn PnP regardless of this default.
    - **Default test-DB strategy.** `AskUserQuestion`: `fork-on-schema-change` (default — only forks when the plan body shows migrations), `always-fork` (defensive — every worktree gets its own test DB regardless), `share` (only safe for solo work; flaky cross-worktree test runs are the cost).
 
    **Follow-up — `implement-plan` default for worktree opt-in.** `AskUserQuestion`: should the `implement-plan` Step 0 question (c) — "run phases in a worktree?" — default to `Yes` or `No`? Lands in `run_options.implement-plan.use_worktree`. Recommend `No` for solo projects + short plans; `Yes` for teams that already use worktrees as part of their workflow.
@@ -124,7 +124,7 @@ Seven skills are part of the foundation set but aren't always needed. Ask explic
 
    Both are skipped, and `parallel_phases` is emitted as `false`, when `prepare-worktree` = No — parallel execution has a hard worktree requirement and `implement-plan` refuses rather than degrading.
 
-   **Follow-up only when `systematic-debugging` = Yes — observability MCP server inventory.** Open prose, not multi-select. Ask the user to name every MCP server already wired up that exposes observability data, in whatever shorthand the team uses (`sentry`, `datadog`, `our-internal-traces`, `grafana-prod`, etc.). The intent is not to pick from a fixed catalogue — that goes stale fast — but to give the systematic-debugging agent a starter list of servers to introspect at Phase 0. Cross-check the answers against any MCP servers actually configured in the project's AI tooling (`.mcp.json`, `~/.claude/mcp_servers.json`, `.codex/mcp.json`, etc.) — if a server is configured but the user didn't mention it, ask whether it carries observability data. The selection lands in `skills.systematic-debugging.observability_mcp_servers` of `.vinta-ai-workflows.yaml` (free-form string array). Empty array is allowed but warn the user that Phase 0 collapses to "local logs only" and production-only bugs without telemetry become a guess factory. The agent will discover specific tool names + categories (error tracking, traces, logs, metrics, alerts, deploys, dashboards) from the live MCP tool list at runtime — see [vinta-derive-skills/resources/systematic-debugging-mcp-tools.md](../vinta-derive-skills/resources/systematic-debugging-mcp-tools.md) for the evidence categories baked into the rendered SKILL.md.
+   **Follow-up only when `systematic-debugging` = Yes — observability MCP server inventory.** First read the MCP servers actually configured in the project's AI tooling (`.mcp.json`, `~/.claude/mcp_servers.json`, `.codex/mcp.json`, etc.). Then ask a multi-select `AskUserQuestion` (header `MCP servers`): *"Which of these MCP servers expose observability data (errors, traces, logs, metrics)?"*, one option per configured server (up to 4; split into further calls when there are more). The free-text field takes any server not listed, in whatever shorthand the team uses (`sentry`, `datadog`, `our-internal-traces`, `grafana-prod`, etc.). When nothing is configured, ask the same thing in prose. The intent is not to pick from a fixed catalogue — that goes stale fast — but to give the systematic-debugging agent a starter list of servers to introspect at Phase 0. The selection lands in `skills.systematic-debugging.observability_mcp_servers` of `.vinta-ai-workflows.yaml` (free-form string array). Empty array is allowed but warn the user that Phase 0 collapses to "local logs only" and production-only bugs without telemetry become a guess factory. The agent will discover specific tool names + categories (error tracking, traces, logs, metrics, alerts, deploys, dashboards) from the live MCP tool list at runtime — see [vinta-derive-skills/resources/systematic-debugging-mcp-tools.md](../vinta-derive-skills/resources/systematic-debugging-mcp-tools.md) for the evidence categories baked into the rendered SKILL.md.
 
    **Cache scaffolding.** Preflight state lives at `.vinta-ai-workflows/cache.yaml` ([`mcp-preflight-cache.v1`](../../schemas/mcp-preflight-cache.v1.schema.json)). The bootstrap orchestrator must:
 
@@ -216,9 +216,9 @@ Rules:
 - When in doubt, reference DESIGN.md — do not invent new values
 ```
 
-Globs may need tuning for the project's actual UI file extensions (Svelte-only projects, RN `.tsx`, etc.). Ask the user once if the analysis surfaced a UI framework not covered by the default glob list; otherwise ship the defaults.
+Globs may need tuning for the project's actual UI file extensions (Svelte-only projects, RN `.tsx`, etc.). When the analysis surfaced a UI framework not covered by the default glob list, ask once via `AskUserQuestion`: `Add <framework> globs (Recommended)` (name the globs you'd add), `Ship the defaults`. Otherwise ship the defaults.
 
-After Step 0: read back the captured decisions (including every per-artifact disposition), confirm via `AskUserQuestion` (`Looks good`, `Some corrections (I'll list)`, `Stop, rethink`).
+After Step 0: read back the captured decisions (including every per-artifact disposition), confirm via `AskUserQuestion` (`Looks good (Recommended)`, `Some corrections (I'll list)`, `Stop, rethink`).
 
 The dispositions become inputs to:
 
@@ -355,7 +355,7 @@ skills:
   # Only emit this block when foundation_skills.prepare-worktree = enabled.
   prepare-worktree:
     worktree_root: <prepare-worktree follow-up — `.claude/worktrees` | `../<repo>-wt-`>
-    deps_strategy: <prepare-worktree follow-up — symlink | copy | reinstall>
+    deps_strategy: <prepare-worktree follow-up — copy | reinstall>
     compose_network: per-worktree
     test_db_strategy: <prepare-worktree follow-up — fork-on-schema-change | always-fork | share>
     summary_dir: .vinta-ai-workflows/worktrees
@@ -488,7 +488,8 @@ Stack-specific skills + agents land in the target only when the user provides te
 
 - **Read before write.** Always check what's in the target repo first. Don't clobber existing AGENTS.md / skills / agents without an explicit confirmation in Step 0.
 - **Stack templates are starting points, not finals.** Each copied skill / agent must be reviewed against the actual project (interview the user about specifics) and edited where the template's assumptions don't fit.
-- **Don't fabricate conventions.** If `vinta-analyze-codebase` doesn't find a thing, ask the user. Don't write "Use bulk_create instead of loop+save" into AGENTS.md just because Django was detected — confirm the team actually follows it.
+- **Every stop for input is a structured question.** See [asking-the-human](../vinta-write-agents-md/resources/asking-the-human.md). A prose question at the end of a long report is the failure mode — the user has to hunt for it and type the answer.
+- **Don't fabricate conventions.** If `vinta-analyze-codebase` doesn't find a thing, ask the user (`AskUserQuestion`, offering what you did find as candidates). Don't write "Use bulk_create instead of loop+save" into AGENTS.md just because Django was detected — confirm the team actually follows it.
 - **Foundation skills are universal.** Every project gets `add-env-var`, `add-e2e-test`, `plan-feature`, `implement-plan`, `create-spec`, `create-qa-use-cases`. The bodies need light per-project edits (test commands, branch conventions) — `vinta-derive-skills` handles that.
 - **Foundation agents are universal.** `implementer` / `reviewer` / `fixer` always. Stack specialists (`deploy-author` for Medplum, `migration-author` for Django) only when the stack matches.
 - **Don't run install-ai-tools-setup until AGENTS.md + agents YAMLs + skills exist.** The setup script reads these files; running it on an empty `ai-tools/` produces nothing useful.

package/skills/vinta-bootstrap-ai-tools/resources/stacks/README.md

@@ -3,7 +3,7 @@
 Each subdirectory here defines a **stack** — a set of detection signals + a description of what kinds of skills + sub-agents typically belong to that stack. The bootstrap flow uses these to:
 
 1. Detect (via [vinta-analyze-codebase](../../../vinta-analyze-codebase/SKILL.md)) which stacks the target project matches.
-2. Ask the user "I detected stack X; do you have skill / sub-agent templates for it? Point me at them" — bootstrap doesn't ship pre-baked content.
+2. Ask the user via `AskUserQuestion` "I detected stack X; do you have skill / sub-agent templates for it?" (`Yes — I'll give the path` with the path typed into the free-text field, `No — record as gap`) — bootstrap doesn't ship pre-baked content.
 3. Copy + adapt the user-provided templates into the target's `ai-tools/skills/` and `ai-tools/agents/`.
 
 This keeps the bootstrap skill **infrastructure only**. Specific skill content (e.g. "how to add a Medplum bot") lives wherever the user keeps their personal / team skill library, not here.

package/skills/vinta-derive-skills/SKILL.md

@@ -31,7 +31,7 @@ Before drafting any new SKILL.md, walk through every entry in `existing_ai_artif
 
 For each name in the foundation set: only emit it (verbatim copy / generate from template / interview-draft) when no existing skill of that name is being migrated or kept. If the user said `Migrate` or `Keep` for an existing `plan-feature/SKILL.md`, **do not overwrite**.
 
-For project-custom skills: never auto-generate something the user already has under a different name. If the user has `<their-name>/SKILL.md` covering ground a stack template would also cover, ask before adding the stack-template version.
+For project-custom skills: never auto-generate something the user already has under a different name. If the user has `<their-name>/SKILL.md` covering ground a stack template would also cover, ask (`AskUserQuestion`) before adding the stack-template version.
 
 ## Foundation set
 
@@ -49,7 +49,7 @@ These are project-agnostic enough to ship as-is. Copy from this skill's [resourc
 | `open-pr-from-context` | [resources/foundation-skills/open-pr-from-context/](resources/foundation-skills/open-pr-from-context/) | Thin SKILL.md wrapper around [scripts/open-pr.sh](resources/foundation-skills/open-pr-from-context/scripts/open-pr.sh) — bash script that publishes one `.vinta-ai-workflows/prs-context/{feature}/{phase}.md` file as a real PR + inline comments via the project's PR CLI (`gh` / `glab`). Used by `implement-plan` (when CLI + `yq`/`jq` are available) and standalone (to publish a `pending` file later). |
 | `deslop-comments` | [resources/foundation-skills/deslop-comments/SKILL.md](resources/foundation-skills/deslop-comments/SKILL.md) | Rewrite comments + doc blocks touched during a task into Simple English — strip AI-slop vocabulary and negative framing; comment-only, no renames or behavior change. **Always ships** — the `review-phase` Layer 2 comment-hygiene check + fix loop dispatch it, and `integrate-phase` / `amend-plan` run it over the PR-context file, so it must exist in the target. Also user-invokable standalone ("deslop these comments"). |
 | `handoff` | [resources/foundation-skills/handoff/SKILL.md](resources/foundation-skills/handoff/SKILL.md) | Write or consume a session-continuation handoff doc under `.vinta-ai-workflows/handoffs/` — goal, current state, decisions + rationale, landmines, next step — so a fresh agent session (or a teammate) resumes in-flight work without re-deriving context. **Always ships** — fully project-agnostic; standalone (no cross-links into the always-on trio). |
-| `prepare-worktree` | [resources/foundation-skills/prepare-worktree/](resources/foundation-skills/prepare-worktree/) | Provision a runnable, isolated git worktree for parallel feature work — symlink dep dirs (or copy / reinstall when the plan churns deps), copy + mutate env files, fork dev + test DBs when migrations are in scope, namespace docker-compose project + network, OS-sandbox the worktree so main-checkout writes are blocked (bundled [scripts/sandbox-run.sh](resources/foundation-skills/prepare-worktree/scripts/sandbox-run.sh) — `sandbox-exec` / `bwrap`), write a teardown-ready summary YAML. Used by `implement-plan` when Step 0 question (c) opts in; standalone for ad-hoc isolation. Opt-in (bucket A + ask-first via the bootstrap's **Optional foundation skills** interview). |
+| `prepare-worktree` | [resources/foundation-skills/prepare-worktree/](resources/foundation-skills/prepare-worktree/) | Provision a runnable, isolated git worktree for parallel feature work — give every worktree its own copy of the dep dirs (copy-on-write clone, or reinstall for virtualenvs / yarn PnP; never a symlink), copy + mutate env files, fork dev + test DBs when migrations are in scope, namespace docker-compose project + network, OS-sandbox the worktree so main-checkout writes are blocked (bundled [scripts/sandbox-run.sh](resources/foundation-skills/prepare-worktree/scripts/sandbox-run.sh) — `sandbox-exec` / `bwrap`), write a teardown-ready summary YAML. Used by `implement-plan` when Step 0 question (c) opts in; standalone for ad-hoc isolation. Opt-in (bucket A + ask-first via the bootstrap's **Optional foundation skills** interview). |
 | `thermo-nuclear-code-quality-review` | [resources/foundation-skills/thermo-nuclear-code-quality-review/SKILL.md](resources/foundation-skills/thermo-nuclear-code-quality-review/SKILL.md) | Opt-in deep structural-maintainability audit of a diff — abstraction quality, giant files, spaghetti-condition growth — harsher than the standard per-phase review; hunts for "code-judo" reframes that collapse branches / helpers / layers rather than polishing them. Read-only; hands each fix to the `fixer` agent. Invoked deliberately by the user, or escalated from the `review-phase` Layer 3 structural-simplification lens. Opt-in (bucket A + ask-first via the bootstrap's **Optional foundation skills** interview). |
 
 These reference each other:
@@ -138,6 +138,8 @@ Shells under `plan-execution/shell/` are thin — most content lives in `plan-ex
 
 **The parallel-lanes seam.** `partials/parallel-lanes.md` carries the DAG scheduler: the graph parse (`DAG_PARSE`), the worktree pool (`LANE_WORKTREE_POOL`), the dependency-derived branch topology (`LANE_TOPOLOGY`), the dispatch loop (`LANE_SCHEDULER`), the tracking-directory schema (`TRACKING_DIR`), and the sibling-lane write guard (`SIBLING_LANE_ISOLATION`, included by `worktree-seam.md#STRAY_WRITE_CHECK`). All six blocks are project-agnostic and carry no new `{{...}}` placeholders of their own beyond ones the shells already substitute (`{{PLAN_DIR}}`, `{{BUILD_CMD}}`, `{{E2E_RUN_OPTION_TRACKING}}`, `{{TRACKING_BRANCH_FIELD}}`, `{{TRACKING_PHASE_BRANCH_FIELD}}`).
 
+**The needs-input seam.** A dispatched agent cannot call the harness's question tool, so it returns its questions as data. `implementer-prompt.md#NEEDS_INPUT` is prompt text (spliced into `FULL` and into `amend-plan` 4b) telling the phase agent to stop and return `status: NEEDS_INPUT` with a `questions:` block. `partials/relay-questions.md#RELAY` is included by `implement-phase`, `review-phase` and `amend-plan`, and turns that block into an `AskUserQuestion` call, records the answer, and continues the agent. The block's shape is the **Asking the human** section of the project's `AGENTS.md` ([source](../vinta-write-agents-md/resources/asking-the-human.md)). Both blocks are project-agnostic and take no `{{...}}` placeholders.
+
 **The dispatched-agent seam.** `partials/dispatched-agent.md` carries the one rule that spans both directions of the unit: the agent doing a phase never dispatches. `CONDUCTOR_ENTRY_GUARD` goes near the top of all four conductors (`implement-plan`, `implement-phase`, `review-phase`, `amend-plan`) and stops an agent that was itself handed one phase — by another conductor, or by [vinta-ai-maestro](https://github.com/vintasoftware/vinta-ai-workflows/tree/main/packages/vinta-ai-maestro) — from re-entering the orchestrator one level down. `NO_NESTED_DISPATCH` is prompt text, spliced into `implementer-prompt.md#INNER_OUTER_LOOP`, so every composed implementer prompt (forward and amend) carries it. Both blocks are project-agnostic and take no `{{...}}` placeholders.
 
 **When `foundation_skills.prepare-worktree` is `disabled`**, parallel execution is impossible (several agents cannot share one working tree). Render the plan-execution unit sequential-only: strip the Step 0 (e) question and the `{If run_options.parallel_phases = true:}` gate from the implementer prompt, and keep the `parallel-lanes` blocks — the scheduler with `max_parallel_lanes = 1` **is** the sequential path, and the DAG still orders the phases correctly. Only the pool provisioning collapses to the single-worktree branch of `WORKROOT_RESOLUTION`.
@@ -283,7 +285,7 @@ Two skills depend on whether the project actually does the thing. Ask via `AskUs
 | `add-e2e-test` | "Does this project have e2e tests, or plan to add them?" Options: `Yes — already has them`, `Yes — planning to add`, `No — skip` | Ask if user has an existing template (path / URL). If yes → copy + adapt. If no → draft from scratch using the canonical structure (see "Skill SKILL.md structure" below) interviewing user about: e2e framework, page-object pattern, auth/storage-state pattern, seed-helpers location, tenant scoping in seeds, screenshot conventions for PRs. |
 | `add-env-var` | "Does this project have a non-trivial env-var propagation flow (multiple files / build configs / CI to update for one new var)?" Options: `Yes`, `No — single .env file is enough` | Ask if user has an existing template. If yes → copy + adapt. If no → draft from scratch interviewing user about every layer the new var must touch (`.env.example`, build tool envPrefix allowlist, build cache hash inputs, app config module, AGENTS.md env section, CI workflows, deploy-time injection). |
 | `add-one-off-script` | "Does this project ever need one-off operational scripts — backfills, cleanups, ad-hoc data fixes?" Options: `Yes — enable`, `No — skip`. Recommend `Yes` for any project with a relational DB; the skill bundles a `BaseOneOffScript` class enforcing dry-run-by-default, idempotent re-runs, batched DB ops, streamed reads, segmented CSV backups (1M cells/file, never nested across tables), interruption-safe signal handlers, and console + filesystem + S3 logging. | Copy [resources/foundation-skills/add-one-off-script/](resources/foundation-skills/add-one-off-script/) into `ai-tools/skills/add-one-off-script/` (SKILL.md + the bundled `resources/one_off_script_base.{py,ts}` templates). Then ask the user whether they want the base class file pre-staged at `<scripts_dir>/one_off/_base.{py,ts}` — default `Yes` for projects whose primary lang is Python or TS. The skill itself prompts to copy the base class on first use if the user said `No` here. |
-| `prepare-worktree` | "Do you ever want to run plans / experiments inside an isolated git worktree (separate runnable copy of the app with its own DB, env, compose stack) instead of swapping branches in the main checkout?" Options: `Yes — enable`, `No — skip`. Recommend `Yes` for projects with long migrations, multi-day plans, or where the user is likely to want parallel concurrent work. | Copy the whole [resources/foundation-skills/prepare-worktree/](resources/foundation-skills/prepare-worktree/) dir into `ai-tools/skills/prepare-worktree/` — both `SKILL.md` and `scripts/sandbox-run.sh` (mark the script executable: `chmod +x ai-tools/skills/prepare-worktree/scripts/sandbox-run.sh`). Then ask three short follow-ups landing in `skills.prepare-worktree.*`: worktree root (default `.claude/worktrees` for claude-code projects, `../<repo>-wt-` sibling dirs otherwise), default deps strategy (`symlink` / `copy` / `reinstall`), default test-DB strategy (`always-fork` / `fork-on-schema-change` / `share`). Also ask whether `implement-plan` should default its Step 0 question (c) to `yes` — lands in `run_options.implement-plan.use_worktree`. |
+| `prepare-worktree` | "Do you ever want to run plans / experiments inside an isolated git worktree (separate runnable copy of the app with its own DB, env, compose stack) instead of swapping branches in the main checkout?" Options: `Yes — enable`, `No — skip`. Recommend `Yes` for projects with long migrations, multi-day plans, or where the user is likely to want parallel concurrent work. | Copy the whole [resources/foundation-skills/prepare-worktree/](resources/foundation-skills/prepare-worktree/) dir into `ai-tools/skills/prepare-worktree/` — both `SKILL.md` and `scripts/sandbox-run.sh` (mark the script executable: `chmod +x ai-tools/skills/prepare-worktree/scripts/sandbox-run.sh`). Then ask three short follow-ups landing in `skills.prepare-worktree.*`: worktree root (default `.claude/worktrees` for claude-code projects, `../<repo>-wt-` sibling dirs otherwise), default deps strategy (`copy` / `reinstall`), default test-DB strategy (`always-fork` / `fork-on-schema-change` / `share`). Also ask whether `implement-plan` should default its Step 0 question (c) to `yes` — lands in `run_options.implement-plan.use_worktree`. |
 
 If user answers "No" to any: don't ship that skill. Record nothing — the foundation set is just smaller.
 
@@ -358,7 +360,7 @@ Length: 100–300 lines. Shorter = under-specified. Longer = should probably spl
 - **Forgetting to substitute placeholders (or expand includes) in the plan-execution skills.** A surviving `{{TEST_CMD}}` or `<!-- include: … -->` is a runtime confusion. Expand every include, substitute every `{{…}}`, and validate before saving. (Angle-bracket runtime slots like `<WORKROOT>` are meant to stay.)
 - **Copying foundation skills and forgetting to scrub source-project paths.** Bundled copies may still carry source-repo paths (e.g. `<source-repo>/ai-plans/`, `apps/<service>/`). Replace with the target's paths.
 - **Asking too many questions for optional skills.** If `vinta-analyze-codebase` shows no e2e dir and the user clearly has no e2e setup, it's OK to skip the question and not ship `add-e2e-test`. Use judgment.
-- **Skipping the foundation copy because "the user already has them".** They probably don't. Confirm by reading the target's `ai-tools/skills/` (if it exists at all). If it does have these, ask the user "refresh from bundled copies, or keep what you have?".
+- **Skipping the foundation copy because "the user already has them".** They probably don't. Confirm by reading the target's `ai-tools/skills/` (if it exists at all). If it does have these, ask via `AskUserQuestion`: `Refresh from bundled copies (Recommended)`, `Keep what you have`.
 
 ## Verification
 

package/skills/vinta-derive-skills/resources/dependency-license-block.md

@@ -24,28 +24,27 @@ Quick lookup:
 If the license is in the forbidden list AND the `(package, license)` pair is **not** listed under **Approved overrides** in AGENTS.md:
 
 1. Stop. Do not run the install command.
-2. Surface the violation to the user with: package name, SPDX identifier, why it's forbidden, link to the upstream license.
-3. Offer alternatives (search the ecosystem for an MIT / Apache-2.0 / BSD-licensed equivalent) before asking for an override.
+2. Search the ecosystem for an MIT / Apache-2.0 / BSD-licensed equivalent first, so the question can name one.
+3. Ask the human (see **Asking the human** in [AGENTS.md](../../../AGENTS.md)). As a sub-agent you cannot ask directly: return `status: NEEDS_INPUT` with one question. Its text carries the package name, SPDX identifier, why it's forbidden, and the upstream license link. Options: `Use <alternative> (Recommended)` (omit when none was found), `Implement without it`, `Record an override`. The orchestrator shows it as a clickable prompt and resumes you with the answer.
 4. If the user grants a one-off override, the orchestrator must record it in `policies.dependency_licenses.allowed_overrides[]` of `.vinta-ai-workflows.yaml` (package + SPDX + one-line reason) before re-running the install. Undocumented overrides leak into the diff and the reviewer agent will flag them.
 
 **License unknown / undeclared.** When the lookup above returns no license, an empty value, `UNKNOWN`, `SEE LICENSE IN <file>`, or only an unstructured `LICENSE` file in the repo with no SPDX identifier, treat it as a **policy decision the user owns** — don't guess, don't auto-infer, don't fall back to "assume MIT". The package may be unlicensed (all-rights-reserved by default in most jurisdictions), proprietary, or simply missing metadata.
 
 1. Stop. Do not run the install command.
-2. Surface to the user: package name, what was found (e.g. "the `license` field is absent in `package.json`", "PyPI metadata returned `UNKNOWN`", "no LICENSE file in the repo"), the upstream repo / registry URL so the user can verify.
-3. Ask via `AskUserQuestion`: `Skip — find a licensed alternative`, `Treat as forbidden — refuse install`, `Treat as allowed — record an override` (the third option only when the user has independently confirmed the license off-channel; record the resolved SPDX in `allowed_overrides[]` with the source in the `reason` field, e.g. `"unlicensed but author confirmed MIT via GitHub issue #42"`).
-4. Don't add the dep until the user picks one of the three.
+2. Ask the human. As a sub-agent, return `status: NEEDS_INPUT` with one question (the orchestrator relays it as a clickable prompt; see **Asking the human** in [AGENTS.md](../../../AGENTS.md)). The question text carries the package name, what was found (e.g. "the `license` field is absent in `package.json`", "PyPI metadata returned `UNKNOWN`", "no LICENSE file in the repo"), and the upstream repo / registry URL so the user can verify. Options: `Find alternative (Recommended)`, `Treat as forbidden`, `Record an override` (only when the user has independently confirmed the license off-channel; record the resolved SPDX in `allowed_overrides[]` with the source in the `reason` field, e.g. `"unlicensed but author confirmed MIT via GitHub issue #42"`).
+3. Don't add the dep until the user picks one of the three.
 
 Transitive deps follow the same rule, but checking every transitive license at install time is impractical — the project's CI (or a separate license-audit run) handles the deep walk. The subagent's responsibility is the **direct** add.
 ```
 
 ### `enforcement: warn`
 
-Identical body, with two edits to the **forbidden-license** branch:
+Identical body, with these edits to the **forbidden-license** branch:
 
 - Step 1 changes to: *"Proceed with the install, but record the violation."*
-- Step 4 reframes the override entry as *"the team should still review and either record an `allowed_overrides` entry or remove the dep."*
+- Step 3 is skipped (no question — the install goes ahead), and step 4 reframes the override entry as *"the team should still review and either record an `allowed_overrides` entry or remove the dep."*
 
-The **License unknown / undeclared** branch is **unchanged** — even in `warn` mode the subagent must stop and ask. Unknown ≠ permissive, and the project has no way to record an override without a confirmed SPDX identifier; treating unknown as "warn + proceed" would silently take on potentially-proprietary code.
+The **License unknown / undeclared** branch is **unchanged** — even in `warn` mode the subagent must stop and return `NEEDS_INPUT`. Unknown ≠ permissive, and the project has no way to record an override without a confirmed SPDX identifier; treating unknown as "warn + proceed" would silently take on potentially-proprietary code.
 
 ### `enforcement: off`
 

package/skills/vinta-derive-skills/resources/foundation-skills/add-one-off-script/SKILL.md

@@ -144,7 +144,7 @@ Stack-specific runtimes can swap the remote sink (Vercel Blob, GCS, Azure Blob,
 
 ### Step 1 — Interrogate the user (NON-NEGOTIABLE)
 
-Use `AskUserQuestion` for the closed-form questions; iterate plain prose for the open ones.
+Use `AskUserQuestion` for the closed-form questions, and for open ones whenever you can propose candidates (model names, table names found in code) — the free-text field covers the rest. Iterate plain prose only when there is nothing to propose.
 
 1. **What does the script do, in one paragraph?** Open prose. The output is the `describe()` body.
 2. **Target rows — what's the SELECT?** Concrete: table, filter predicate, ordering. The agent translates this into the `iter_targets()` body. If the user can't write the SELECT confidently, push back — they don't have a clear enough picture to safely run the script yet.

package/skills/vinta-derive-skills/resources/foundation-skills/create-qa-use-cases/SKILL.md

@@ -35,7 +35,7 @@ For everything **not** answered by the active spec/plan, ask via `AskUserQuestio
 
 **A. App boundaries**
 1. How many apps does this project have, and what are their names? (e.g. `Patient App`, `Provider App`, `Admin Console`, single SaaS app named `<Product>`.)
-2. ID prefix per app — typically a 2-letter abbreviation. Defaults: `PA` for "patient/public app", `PR` for "provider/admin app". Confirm or override.
+2. ID prefix per app — typically a 2-letter abbreviation. `AskUserQuestion` per app with the derived abbreviation first (` (Recommended)`), e.g. `PA` for "patient/public app", `PR` for "provider/admin app"; free text overrides.
 3. Does any app have unauthenticated routes that need use-case entries (registration, public referral, marketing landing)? Those entries note `(unauthenticated)` in the role.
 
 **B. Roles**
@@ -49,7 +49,7 @@ For everything **not** answered by the active spec/plan, ask via `AskUserQuestio
 
 **D. ID assignment**
 1. Order: append in the order use cases appear in the active spec (**Decisions → Use-cases** first, then any plan-only phases). Don't reshuffle.
-2. Default starting numbers `PA001` / `PR001`. Confirm or override.
+2. Starting numbers: `AskUserQuestion` with `Start at 001 (Recommended)` and, when existing ids were found elsewhere (spec filenames, tickets), `Continue after <highest id>`.
 
 ### Clarity loop
 
@@ -211,7 +211,7 @@ or reuse a retired ID. The e2e spec filenames mirror these IDs one-to-one.
 ## Pitfalls
 
 - **Overwriting an existing file.** Bootstrap is one-shot. If the file exists, append via add-e2e-test, don't regenerate — existing ids are referenced by spec filenames + bug tickets and can't move.
-- **Inventing use cases from project name alone.** If the spec/plan doesn't describe a flow, don't add a stub. Empty checklist + no real flow = noise. Ask the user; if they don't have one, leave it out.
+- **Inventing use cases from project name alone.** If the spec/plan doesn't describe a flow, don't add a stub. Empty checklist + no real flow = noise. Ask via `AskUserQuestion` (`Leave it out (Recommended)`, `I'll describe the flow`); if they don't have one, leave it out.
 - **Mixing role-coded admin with project-admin.** Many systems have both (a "Clinical Ops" role + a flag like `ProjectMembership.admin === true`). List both rows in the role table if both apply — they map to different storage states / permission paths in tests.
 - **Putting implementation details in steps.** "Create QuestionnaireResponse with linkId=first-name" reads to QA as gibberish. "Fill out the intake form" is the right level. Implementation details belong in the e2e spec or seed helper, not here.
 - **Numbering by importance.** Numbers reflect order of arrival, not priority. PA047 isn't more important than PA003 — it just came later. Don't try to keep "core" use cases at low numbers; that path leads to renumbering.

package/skills/vinta-derive-skills/resources/foundation-skills/create-spec/SKILL.md

@@ -19,12 +19,15 @@ For finite-set answers, **list options**. Provide one-sentence **why** so they u
 
 ### Use `AskUserQuestion` for finite-choice questions
 
-Every interview question with discrete answer set — yes/no, named option, finite enum, hypothesis-vs-known-requirement, idempotency mode, concurrency rule — **must** issue via `AskUserQuestion` tool. Use plain prose only when answer genuinely open-ended (problem narrative, walking through journey, free-form motivation, hard deadline date).
+Every interview question with discrete answer set — yes/no, named option, finite enum, hypothesis-vs-known-requirement, idempotency mode, concurrency rule — **must** issue via `AskUserQuestion` tool. `AskUserQuestion` = Claude Code's name; on other harnesses use the equivalent structured question tool (OpenCode `question`, Codex `request_user_input`, Cursor `AskQuestion`, Copilot `askQuestions`, Gemini `ask_user` — see **Asking the human** in [AGENTS.md](../../../AGENTS.md)).
+
+Open-ended questions ride the tool too whenever you can propose 2–4 candidate answers from the prompt, codebase, or earlier answers; the free-text field covers the rest. Plain prose only when no candidate exists (problem narrative, walking through journey, hard deadline date) — one question per message.
 
 Pattern per group:
 
 - One `AskUserQuestion` call per group, batch multiple questions into same call when tool supports (each question carry own option set).
-- Short label per option; rationale ("default: per-user — confirm or override") goes in question header, not option label.
+- Short label per option; rationale ("default: per-user — confirm or override") goes in question text, not option label. Default option first, label ends ` (Recommended)`. No "Other" option — the tool adds free text.
+- Max 4 questions per call (3 on Codex); split bigger groups into consecutive calls.
 - Open-ended sub-questions in same group → fall back to plain prose for those, send closed-form ones via `AskUserQuestion`. Don't force finite list when genuinely free text.
 
 If `AskUserQuestion` in deferred-tool list + not yet schema-loaded, call anyway — tool name fixed + harness surfaces it. **Never** flatten ten questions into one prose paragraph because tool not pre-loaded; that failure mode this skill exists to prevent.

package/skills/vinta-derive-skills/resources/foundation-skills/handoff/SKILL.md

@@ -77,12 +77,12 @@ Report the file path. Note that `.vinta-ai-workflows/` is typically gitignored
 
 ## Resume mode
 
-1. **Read the handoff doc** in full. If the user didn't name one, list `.vinta-ai-workflows/handoffs/` and pick the most recent that isn't superseded; confirm the pick with the user if more than one task is plausible.
+1. **Read the handoff doc** in full. If the user didn't name one, list `.vinta-ai-workflows/handoffs/` and pick the most recent that isn't superseded. When more than one task is plausible, ask via `AskUserQuestion`, one option per candidate (title + date), most recent first.
 2. **Verify its claims against the repo before trusting them.** The repo may have moved since the handoff was written:
-   - Named branch exists and you're on it (or switch after confirming with the user).
+   - Named branch exists and you're on it (or switch after an `AskUserQuestion`: `Switch to <branch> (Recommended)`, `Stay on <current>`).
    - Cited commits exist (`git log`), cited files exist, `git status` matches the described uncommitted state.
    - Re-run the cheapest verification command from the **Verification** section to confirm the "done" claims still hold.
-3. **On mismatch, stop and reconcile** — tell the user what the handoff claims vs. what the repo shows. Never continue from stale premises.
+3. **On mismatch, stop and reconcile** — show what the handoff claims vs. what the repo shows, then ask via `AskUserQuestion`: `Trust the repo, update the plan (Recommended)`, `Investigate the gap first`, `Stop`. Never continue from stale premises.
 4. **Adopt the decisions.** Treat **Decisions made** as settled unless the user reopens one; do not re-explore rejected alternatives.
 5. **Continue from Next step.** When the work later stops again unfinished, write a fresh handoff (write mode) superseding this one.
 

package/skills/vinta-derive-skills/resources/foundation-skills/plan-feature/SKILL.md

@@ -19,19 +19,21 @@ Drop irrelevant groups; don't drop questions inside relevant group:
 
 ### Use `AskUserQuestion` for finite-choice questions
 
-Every question in groups B–J with discrete answer set — yes/no, named option, finite enum — **must** go through `AskUserQuestion` tool, not free-form prose. Why:
+Every question in groups B–J with discrete answer set — yes/no, named option, finite enum — **must** go through `AskUserQuestion` tool, not free-form prose. `AskUserQuestion` = Claude Code's name; on other harnesses use the equivalent structured question tool (OpenCode `question`, Codex `request_user_input`, Cursor `AskQuestion`, Copilot `askQuestions`, Gemini `ask_user` — see **Asking the human** in [AGENTS.md](../../../AGENTS.md)). Why:
 
 - User picks; no retyping context.
 - Multiple related questions ride one `AskUserQuestion` call (tool accepts list of questions, each own option set). Batch per group: one call for the **Data model & storage** group, one for the **API surface** group, etc.
-- Short option label per choice; rationale ("default: per-user — confirm or override") goes in question header, not option labels.
+- Short option label per choice; rationale ("default: per-user — confirm or override") goes in question text, not option labels. Default option first, label ends ` (Recommended)`.
+- Max 4 questions per call (3 on Codex) — split bigger groups into consecutive calls.
+- No "Other" option — tool always adds free-text field.
 
-Plain prose (no tool) **only** when answer genuinely open-ended: "walk me through user journey", "what success look like in your words", "what deadline driver". Group A mostly prose; B–J mostly closed-choice.
+**Open-ended questions ride the tool too when you can propose candidates.** Spec, codebase, or earlier answers usually suggest 2–4 plausible answers ("Primary actor?" → roles found in code; "Success metric?" → metrics the spec names). Offer those; free-text field covers the rest. Plain prose (no tool) **only** when no candidate exists at all: "walk me through user journey", "what deadline driver". Group A often prose; B–J closed-choice.
 
 ### Iterative asking when no `AskUserQuestion` (or question open-ended)
 
 Two cases force iterative single-question mode:
 
-1. **`AskUserQuestion` genuinely unavailable** (harness errored on call, not deferred). Try once — confirm actually missing, not schema-deferred.
+1. **No structured question tool** (harness errored on call, not deferred). Try once — confirm actually missing, not schema-deferred. Then each closed-choice question becomes numbered option list ending "Reply with option number, or type your own answer".
 2. **Question genuinely open-ended** (no finite option set — narrative, journey, free-form motivation, deadline date).
 
 Both cases: **ask one question at a time, wait for answer, then ask next.** Don't dump 5 open questions in one paragraph — user reads three, answers two, third gets lost. Iterate: