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

name	description	argument-hint	model	allowed-tools
ultrabrief-local	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.	[--quick] <task description>	opus	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:

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:

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:

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:

{
  "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.