ktg-plugin-marketplace/plugins/ultraplan-local/commands/ultrabrief-local.md

---
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] <task description>"
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 <dir>  →  research/*.md
/ultraplan-local --project <dir>  →  plan.md
/ultraexecute-local --project <dir>  →  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 <task description>
       /ultrabrief-local --quick <task description>

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.