--- name: ultrabrief-local description: Interactive interview that produces a task brief with explicit research plan. Feeds /ultraresearch-local and /ultraplan-local. Optionally orchestrates the full pipeline end-to-end. argument-hint: "[--quick] " model: opus allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion --- # Ultrabrief Local v2.0 Interactive requirements-gathering command. Produces a **task brief** — a structured markdown file that declares intent, goal, constraints, and an **explicit research plan** with copy-paste-ready `/ultraresearch-local` commands. Pipeline position: ``` /ultrabrief-local → brief.md (this command) /ultraresearch-local --project → research/*.md /ultraplan-local --project → plan.md /ultraexecute-local --project → execution ``` The brief is the contract between the user's intent and `/ultraplan-local`. Every decision the plan makes must trace back to content in the brief. **This command is always interactive.** There is no background mode — the interview requires user input. After the brief is written, the command optionally orchestrates the rest of the pipeline (research + plan) in foreground if the user opts in. ## Phase 1 — Parse mode and validate input Parse `$ARGUMENTS`: 1. If arguments start with `--quick`: set **mode = quick**. Interview is shorter (3-4 questions instead of 5-8). Strip the flag; remainder is the task description. 2. Otherwise: **mode = default**. Full interview (5-8 questions). If no task description is provided, output usage and stop: ``` Usage: /ultrabrief-local /ultrabrief-local --quick Modes: default Full interview (5-8 questions) → brief with research plan --quick Short interview (3-4 questions) → brief with research plan Examples: /ultrabrief-local Add user authentication with JWT tokens /ultrabrief-local --quick Add rate limiting to the API /ultrabrief-local Migrate from Express to Fastify ``` Report: ``` Mode: {default | quick} Task: {task description} ``` ## Phase 2 — Generate slug and create project directory Generate a slug from the task description: first 3-4 meaningful words, lowercase, hyphens. Example: "Migrate from Express to Fastify" → `fastify-migration`. Set today's date as `YYYY-MM-DD` (UTC). Create the project directory: ```bash PROJECT_DIR=".claude/projects/{YYYY-MM-DD}-{slug}" mkdir -p "$PROJECT_DIR/research" ``` Report: ``` Project directory: .claude/projects/{YYYY-MM-DD}-{slug}/ ``` If the directory already exists and is non-empty, warn and ask: > "Directory {path} exists. Overwrite, reuse (keep existing files), or pick new slug?" Use `AskUserQuestion` with three options. If "pick new slug", ask for a new slug and restart Phase 2. ## Phase 3 — Interview Use `AskUserQuestion` throughout. **Ask one question at a time.** Never dump all questions at once. Follow up based on answers. ### Interview flow **Question 1 (always) — Intent:** > "What is the motivation for this task? Why does it matter? What happens > if we don't do it? (The plan will use this to justify every implementation > decision.)" **Question 2 (always) — Goal:** > "What does success look like concretely? Describe the end state in > 1-3 sentences — specific enough to disagree with." **Question 3 (always) — Success criteria:** > "How will we verify it's done? List 2-4 specific, testable conditions > (commands to run, observations, metrics). Avoid 'it works'." **Question 4 (usually) — Non-goals:** > "What is explicitly NOT in scope? (Prevents scope-guardian flagging gaps > for things we deliberately don't do.)" **Question 5 (conditional) — Constraints:** > "Are there technical, time, or resource constraints? (Dependencies, > compatibility, deadlines, budget.)" > > Skip if the user already mentioned constraints. **Question 6 (conditional) — Preferences:** > "Preferences on libraries, patterns, or architectural style?" > > Skip for small tasks or when constraints already imply them. **Question 7 (conditional) — Non-functional requirements:** > "Performance, security, accessibility, or scalability targets? (Quantified > where possible.)" > > Skip if not applicable. **Question 8 (conditional) — Prior attempts:** > "Has this been tried before? What worked or failed?" > > Skip if the task is clearly fresh. ### Adaptive depth After each answer: - **Detailed technical answer (2+ sentences, domain vocabulary):** skip obvious follow-ups the user already covered. Aim for 4-5 total questions. - **Short or uncertain answer ("I don't know", "not sure", vague):** offer alternatives instead of open questions. Record uncertainty as an open assumption. - **"Skip" / "just make it" / "proceed":** stop interviewing. Write a minimal brief from the task description and answers so far. Mark uncovered sections as "Not discussed — no constraints assumed." ### Quick mode If **mode = quick**, ask only Questions 1, 2, 3, and 4. Maximum 4 questions. Skip the rest. ### Research topic identification (CRITICAL) As the interview progresses, identify topics that will need research for the plan to be high-confidence. Watch for: - **Unfamiliar technologies** — libraries, frameworks, protocols not clearly present in the codebase - **Version upgrades** — migrating to a new major version - **Security-sensitive decisions** — auth, crypto, data handling - **Architectural choices** — pattern X vs Y, library A vs B - **Unknown integrations** — third-party APIs, external services - **Compliance / legal** — GDPR, accessibility, industry regulations For each potential topic, probe briefly: > "Do you already know {topic}, or should I plan a research step for it?" Record: - Topic title (short) - Why it matters for the plan - Exact research question (phrased for `/ultraresearch-local`) - Suggested scope (local / external / both) - Confidence needed (high / medium / low) - Estimated cost (quick / standard / deep) If the user says "I know this" — do not add it as a topic. Trust the user. If no topics emerge: `research_topics = 0` is valid. Not every task needs external research. ## Phase 4 — Write the brief Read the brief template: `@${CLAUDE_PLUGIN_ROOT}/templates/ultrabrief-template.md` Write the brief to: `{PROJECT_DIR}/brief.md`. Fill in every section based on interview answers: - **Frontmatter:** populate `task`, `slug`, `project_dir`, `research_topics`, `research_status: pending`, `auto_research: false` (will update in Phase 5 if user opts in), `interview_turns`, `source: interview`. - **Intent:** expand the user's motivation into 3-5 sentences. This is load-bearing — be explicit. - **Goal:** concrete end state. - **Non-Goals:** from user's answer, or empty list with note. - **Constraints / Preferences / NFRs:** from user's answers. Mark "Not discussed — no constraints assumed" if not covered. - **Success Criteria:** falsifiable commands/observations. Reject vague criteria from the user — ask for a concrete version if needed. - **Research Plan:** one section per identified topic, with the full structure from the template. If 0 topics, write the "No external research needed" note. - **Open Questions / Assumptions:** from "I don't know" answers and implicit gaps. - **Prior Attempts:** from user's answer, or "None — fresh task." Populate the "How to continue" footer with the actual project path and topic questions. Report: ``` Brief written: {PROJECT_DIR}/brief.md Research topics identified: {N} ``` ## Phase 5 — Auto-orchestration opt-in (if research_topics > 0) **Skip this phase if research_topics = 0.** Proceed directly to Phase 6. Ask the user via `AskUserQuestion`: **Question:** "You have {N} research topic(s). How do you want to proceed?" | Option | Description | |--------|-------------| | **Manual (default)** | Print the commands. You run `/ultraresearch-local` and `/ultraplan-local` yourself, choosing depth per topic. | | **Auto (managed by Claude Code)** | I run all {N} research topics in parallel, then automatically trigger `/ultraplan-local` when research completes. Foreground — this session blocks until the plan is ready. | ### Manual path (default) Output: ``` ## Brief complete Project: {PROJECT_DIR}/ Brief: {PROJECT_DIR}/brief.md Research topics: {N} Next steps (run in order or parallel): {For each topic:} /ultraresearch-local --project {PROJECT_DIR} --external "{topic question}" Then: /ultraplan-local --project {PROJECT_DIR} Then: /ultraexecute-local --project {PROJECT_DIR} ``` Stop. Do not continue to Phase 6. ### Auto path Set `auto_research: true` in the brief's frontmatter (edit the file). Proceed to Phase 6. ## Phase 6 — Auto research dispatch (auto path only) **Runs only when user opted into auto mode.** ### Step 6a — Billing safety check Run via Bash: ```bash echo "${ANTHROPIC_API_KEY:+SET}" ``` If `SET`, warn via `AskUserQuestion`: **Question:** "`ANTHROPIC_API_KEY` is set. Running {N} parallel research jobs in background will bill your API account (not your Claude subscription). Continue?" | Option | Action | |--------|--------| | **Continue — API billing** | Proceed. | | **Switch to sequential** | Run topics one at a time in foreground instead of parallel background. Stays on subscription for this session. | | **Cancel — do manual** | Revert to manual path (print commands, stop). | If cancelled → fall back to manual path output and stop. If sequential → note and proceed (Step 6b runs foreground, one at a time). If continue → proceed with parallel background. ### Step 6b — Launch research jobs Set `research_status: in_progress` in the brief's frontmatter. For each research topic (index i = 1 .. N): Launch the **research-orchestrator** agent with this prompt: ``` Research question: {topic i question} Dimensions: {infer 3-5 dimensions from topic confidence + cost hints} Mode: {default if cost=standard or deep; quick if cost=quick} Scope: {topic i scope hint: local | external | both} Brief destination: {PROJECT_DIR}/research/{NN}-{topic-slug}.md Plugin root: ${CLAUDE_PLUGIN_ROOT} ``` Where `{NN}` is zero-padded index (`01`, `02`, ...) and `{topic-slug}` is the topic title slugified. **Parallel (default auto path):** launch all N research-orchestrator agents in parallel via a single message with multiple Agent tool calls, all `run_in_background: true`. **Do not wait** in the same message — return control. You will be notified when each completes. **Sequential (if user chose sequential):** launch one research-orchestrator at a time, foreground (no `run_in_background`), wait for completion, then launch the next. ### Step 6c — Wait for all research to complete Wait for all research agent notifications. When all {N} have completed, verify each research brief file exists: ```bash ls -1 {PROJECT_DIR}/research/*.md | wc -l ``` Expected count: N. If any are missing, report and ask the user how to proceed (retry, skip missing topic, cancel). Update brief frontmatter: `research_status: complete`. ### Step 6d — Auto-trigger planning Launch the **planning-orchestrator** agent with this prompt: ``` Brief file: {PROJECT_DIR}/brief.md Project dir: {PROJECT_DIR} Task: {task description from brief} Mode: default Plan destination: {PROJECT_DIR}/plan.md Plugin root: ${CLAUDE_PLUGIN_ROOT} Research briefs: {list of {PROJECT_DIR}/research/*.md files} Read the brief file and every research brief. Execute your full planning workflow. Write the plan to the destination path. ``` Launch foreground (wait for completion — user asked for full auto). ### Step 6e — Report completion When the planning-orchestrator finishes, present: ``` ## Ultrabrief + Ultraresearch + Ultraplan Complete (auto mode) **Project:** {PROJECT_DIR}/ **Brief:** {PROJECT_DIR}/brief.md **Research briefs:** {N} in {PROJECT_DIR}/research/ **Plan:** {PROJECT_DIR}/plan.md ### Pipeline summary | Step | Status | |------|--------| | Brief | Complete ({interview_turns} interview turns) | | Research | Complete ({N} topics, {P} parallel / {S} sequential) | | Plan | Complete ({steps} steps, critic: {verdict}) | Next: /ultraexecute-local --project {PROJECT_DIR} Or: /ultraexecute-local --dry-run --project {PROJECT_DIR} # preview /ultraexecute-local --validate --project {PROJECT_DIR} # schema check ``` ## Phase 7 — Stats tracking Append one record to `${CLAUDE_PLUGIN_DATA}/ultrabrief-stats.jsonl`: ```json { "ts": "{ISO-8601}", "task": "{task description (first 100 chars)}", "slug": "{slug}", "mode": "{default | quick}", "interview_turns": {N}, "research_topics": {N}, "auto_research": {true | false}, "auto_result": "{completed | cancelled | failed | manual}", "project_dir": "{path}" } ``` If `${CLAUDE_PLUGIN_DATA}` is not set or not writable, skip silently. Never let stats failures block the workflow. ## Hard rules 1. **Interactive only.** This command requires user input. There is no `--fg` or background mode — the interview cannot run headless. 2. **Brief is the contract.** Every section must have substantive content or an explicit "Not discussed" note. No empty sections. 3. **Intent is load-bearing.** Do not accept a one-line intent. Expand with the user until motivation is clear — the plan and every review agent will trace decisions back to this. 4. **Research topics must be answerable.** Each topic's research question must be phrased so `/ultraresearch-local` can answer it. If a topic is too vague, split or reformulate before writing. 5. **Never invent research topics the user did not agree to.** Topics come from the interview. If the user says "I know this", respect it. 6. **Project dir is the single source of truth.** Every artifact (brief, research briefs, plan, progress) lives in one project directory. Never scatter files across `.claude/research/`, `.claude/plans/`, etc. 7. **Auto mode blocks foreground.** If the user opts into auto, this session waits for research + planning to complete. Document this in the opt-in question. 8. **Privacy:** never log prompt text, secrets, or credentials.