gza-task-draft

name	gza-task-draft
description	Guide user through deliberate task creation with clarification and refinement before running gza add
allowed-tools	Read, Bash(uv run gza add:*), AskUserQuestion
version	1.0.0
public	true

Draft Gza Task

Guide the user through a deliberate task creation process: clarify scope, surface risks, draft a prompt, get approval, then run uv run gza add.

Step 1: Read conventions

Read /workspace/AGENTS.md — specifically the "Creating Tasks from Conversations" section — to understand task types, flags, and prompt conventions.

Step 2: Assess description detail

Evaluate how detailed the user's description already is:

If vague or missing key context (objective unclear, scope undefined, approach unspecified): ask clarifying questions using AskUserQuestion (max 4 questions per call, 2–4 options each).

Focus on what matters most:

• What is the core objective / what problem does this solve?
• What type of work is this? (explore/plan/implement/review/task)
• Are there constraints, dependencies, or related tasks?
• What does "done" look like?

If already detailed (clear objective, known scope, specific requirements): skip to Step 3 directly.

Step 3: Draft the prompt + surface concerns

Draft a task prompt that:

• States the objective clearly and specifically
• References file paths, modules, or components when known
• Sets scope (what's in and out)
• Includes acceptance criteria for implement tasks
• Includes non-goals for implement tasks so the agent does not expand scope silently
• Names required tests or concrete failure modes to cover when known
• Calls out docs/help/config updates when operator-facing behavior changes
• Is appropriately sized (one task, one objective)

For implement tasks, push toward a prompt shape like:

• Objective
• Acceptance criteria
• Non-goals
• Relevant files/modules or affected subsystem
• Required tests
• Required docs/help/config updates, if applicable

If too many of those fields are unknown, ambiguous, or cross-cutting, recommend splitting the work or creating a plan task first rather than drafting a vague implement prompt.

Also identify and surface:

• Risks: What could go wrong or cause rework?
• Ambiguities: Unclear requirements that could derail the task
• Alternatives: Different approaches worth considering
• Sequencing: Should this be split (plan first, then implement)? Does it need --depends-on or --based-on?

When reviewing the draft with the user, explicitly check for:

• Missing acceptance criteria
• Missing non-goals or scope boundaries
• Missing targeted test expectations
• Missing docs/help/config expectations for operator-facing changes

Present the draft prompt and concerns clearly to the user.

Step 4: Propose flags

Based on the discussion, suggest the full uv run gza add command. For any multi-line prompt, write the body to a tempfile (Write tool, e.g. /tmp/gza-prompt-<short-name>.md) and pass --prompt-file. Only inline as a positional arg for single-line prompts.

# Single-line:
uv run gza add [FLAGS] "short prompt"

# Multi-line (the common case for drafted tasks):
uv run gza add [FLAGS] --prompt-file /tmp/gza-prompt-<short-name>.md

Do not use "$(cat <<'EOF' ... EOF)" to inline multi-line prompts — backticks, $, parens, and indented code blocks in the body break it, silently mangling the prompt or leaking the body to bash as commands. The tempfile path is always safe.

Flags to consider:

• --type — task (default), explore, plan, implement, review
• --review — auto-create review task after implementation (for significant changes)
• --tag TAG — attach a tag to relate the task to other work (repeatable)
• --depends-on ID — task cannot start until another completes
• --based-on ID — implementation draws from a previous task's output
• No flag needed for simple tasks

Step 5: Get approval

Use AskUserQuestion to let the user review the draft:

Options:

• Approve — run uv run gza add as proposed
• Refine prompt — let user provide corrections (ask what to change, then revise and re-present)
• Adjust flags — type, tags, or dependencies need changing (ask what, revise, re-present)
• Split into multiple tasks — break into smaller tasks (draft each separately)

Repeat Steps 3–5 if refinement is needed.

Step 6: Run uv run gza add

Once approved:

• For a multi-line prompt, Write it to /tmp/gza-prompt-<short-name>.md and run uv run gza add ... --prompt-file <path>.
• For a single-line prompt, pass it as the positional arg.

Show the created task ID and confirm type/tags if set.

Important notes

• One task, one objective — if the user describes multiple distinct goals, create multiple tasks
• Plan before implement — for complex features, suggest a --type plan task first
• Proactively flag risks — better to surface ambiguity now than after the task runs
• Keep prompts specific — vague prompts produce vague results
• Implement prompts need closure conditions — acceptance criteria, non-goals, tests, and docs/help impact should be explicit whenever relevant