Skill

describe-task

Creates a Task Brief from a plain-language problem description. Clarifies the problem with the user, researches the codebase for entry points and relevant files, then emits a v1 Task Brief for use by /implement. Companion to /load-task for describing work directly rather than selecting from the backlog.

Invocation

How this skill is triggered — by the user, by Claude, or both

Slash command

/code-forge:describe-task

User invocable

Model invocable

Inline context

Default effort

Tool Access

This skill is limited to the following tools:

TeamCreateAgentTaskCreateTaskUpdateTaskGetRead(~/**/.claude/skills/researcher-protocol/references/task-brief.md)Read(~/.claude/plugins/**/skills/researcher-protocol/references/task-brief.md)Bash(git rev-parse --git-dir)Bash(git rev-parse HEAD)Bash(git reset --hard *)AskUserQuestionEnterWorktreeRead

Context Preview

The summary Claude sees in its skill listing — used to decide when to auto-load this skill

Creates a Task Brief from a plain-language problem description instead of selecting from the project backlog. Uses a persistent code-forge:researcher-agent teammate to clarify the problem, research the codebase, and return a structured brief.

SKILL.md

242 lines · ~2.3k tokens

Stats

LanguageShell

Stars0

MaintenanceExcellent

Last CommitJun 6, 2026

Actions

View Source View Plugin View on GitHub View README

Stats

Actions

Describe Task

Reference: code-forge:orchestrator-protocol · code-forge:researcher-protocol · task-brief-format

Step 0 — Load code-forge:orchestrator-protocol

Load /code-forge:orchestrator-protocol now. It defines the message formats, result blocks, and brief contract used in the steps below. Do not proceed until it is loaded.

Step 1 — Capture the Description

Check the user's invocation arguments. If a description was provided (as a single quoted string or multi-word argument), use it as <DESCRIPTION>. If no argument was given, prompt the user:

Use AskUserQuestion with a single question:

Header: "Problem description"
Question: "Describe the problem or task you want to work on. Be as specific as you can about what should change and why."
Options: (omit; this is a free-text response)

Capture the user's answer as <DESCRIPTION>. Proceed to Step 2.

Step 2 — Clarify the Description

Parse <DESCRIPTION> and identify what is Known or Unknown:

What to infer	Derived from user answer
Change type (Bug / Chore / Enhancement)	Is something broken, or is this new/improved/cleaned up?
Done condition — what the user can observe when it works	"How will you know it's working?"
Starting point hint — a file, feature name, or module	"Which part of the code is involved, if you know?"

For each Unknown, include the corresponding question in the batch below. Do not proceed to Step 3 while any field is Unknown.

Use AskUserQuestion to batch all outstanding clarifications:

Include these questions as appropriate (omit those where the answer is already clear from the description):

Q1 — Nature of the change (include if type is not clear):
- Header: "Change type"
- Question: "What kind of change is this?"
- Options:
  - "Something is broken" (→ Bug)
  - "Add or improve something" (→ Enhancement)
  - "Cleanup, refactor, or update" (→ Chore)
Q2 — Done condition (include only if description lacks a concrete outcome):
- Header: "Success condition"
- Question: "What should work differently when this is done?"
- Options: (omit; free-text answer)
Q3 — Codebase focus (include only if description is vague about location):
- Header: "Codebase area"
- Question: "Do you know which file, feature, or area of the code is involved?"
- Options: (omit; free-text, optional)

Always use AskUserQuestion for this step — even if only one field is unknown. Record all answers.

Synthesize the answers into a context_overrides string: comma-separated key=value pairs, e.g., type=Bug, criteria=Should log retry attempts, area=api/http.go. Pass this to Step 3 below.

Step 3 — Create Pipeline Team, Worktree, Spawn Researcher, and Assign Task

Create an empty named team, catching any failure:

try:
  TeamCreate(name: "pipeline-team")
catch error where error.message contains "Already leading team 'pipeline-team'"
               or error.message contains "Team 'pipeline-team' already exists at":
  emit the pipeline-team-exists error block from code-forge:orchestrator-protocol/references/error-messages.md verbatim
  stop — do not spawn agents or proceed further

Compute a pipeline run ID using the format run-<YYYYMMDDTHHmmss> (e.g., run-20260525T143000). Store as PIPELINE_RUN_ID.

Create the worktree now (before spawning any agent work):
```
HEAD = Bash("git rev-parse HEAD").trim()
EnterWorktree(name: "<PIPELINE_RUN_ID>")
Bash("git reset --hard <HEAD>")
```

Spawn the researcher into it:

Agent(
  subagent_type: "code-forge:researcher-agent",
  name: "researcher",
  team_name: "pipeline-team",
  prompt: "You are the researcher in the pipeline. Load the code-forge:researcher-protocol skill immediately, then await task assignment from the team-lead."
)

Store RESEARCHER_NAME = "researcher". Use this name in all subsequent TaskUpdate calls. Team member names persist across idle/resume cycles — do not convert to UUIDs.

Create the sentinel task and assign it to team-lead before spawning any agent work. This keeps the task list from being auto-cleared by the UI while the orchestrator is reading back the researcher's result:

TaskCreate(
  subject     = "Pipeline orchestration — <PIPELINE_RUN_ID>",
  description = "Held in_progress by the team-lead to prevent UI auto-cleanup of the task list while the orchestrator reads back researcher results.",
  metadata    = {
    pipeline_run_id: "<PIPELINE_RUN_ID>",
    role:            "team-lead",
    phase:           "orchestration",
    iteration:       0,
    result_status:   null,
    result_type:     null,
    result_block:    null,
    claimed_at:      null,
    completed_at:    null,
    archived:        false
  }
)

Store the returned task ID as SENTINEL_TASK_ID. Then assign it immediately:

TaskUpdate(
  taskId   = <SENTINEL_TASK_ID>,
  owner    = "team-lead",
  status   = "in_progress",
  metadata = { claimed_at: "<ISO 8601 timestamp>" }
)

Create the researcher task via TaskCreate:

TaskCreate(
  subject     = "Describe and research task from user description",
  description = "mode: describe\ngoal: Produce a Task Brief from a user-provided description\ndescription: <full DESCRIPTION text from Step 1>\ncontext_overrides: <key=value pairs from Step 2; omit if empty>\nreturn_format: Task Brief",
  metadata    = {
    pipeline_run_id: "<PIPELINE_RUN_ID>",
    role:            "researcher",
    phase:           "research",
    iteration:       0,
    result_status:   null,
    result_type:     null,
    result_block:    null,
    claimed_at:      null,
    completed_at:    null,
    archived:        false
  }
)

Store the returned task ID as RESEARCHER_TASK_ID.

Assign the task to the researcher via TaskUpdate (this wakes the agent):

TaskUpdate(
  taskId   = <RESEARCHER_TASK_ID>,
  owner    = "researcher",
  status   = "in_progress",
  metadata = { claimed_at: "<ISO 8601 timestamp>" }
)

The researcher automatically loads the code-forge:researcher-protocol skill.

End your response turn. There is no tool that implements waiting. The next message you receive will be the task completion notification from the harness. When that notification arrives, proceed to Step 4.

Step 4 — Validate Brief

Retrieve the completed researcher task record:

task = TaskGet(taskId = <RESEARCHER_TASK_ID>)

Metadata fields on the returned task object:

task.metadata.result_status — "success", "failure", or "escalation"
task.metadata.result_type — "Task Brief", "Failure Report", or "NEEDS_ESCALATION"

Branch on task.metadata.result_status:

If "failure": read brief.md for the Failure Report content, surface it verbatim, and stop.
If "escalation": read brief.md for the NEEDS_ESCALATION content, surface it verbatim, and stop.
If "success": read brief.md to obtain the Task Brief text.

brief_text = Read("brief.md")

After reading the Task Brief, validate required fields per the brief contract in code-forge:orchestrator-protocol.

If any required field is missing, surface the partial brief to the user with a note identifying the gaps. Do not emit an incomplete brief.

Step 5 — Emit Result

Following the /orchestrate result contract, emit the Task Brief verbatim to the user without reformatting or summary.

Then complete the sentinel task:

TaskUpdate(
  taskId   = <SENTINEL_TASK_ID>,
  status   = "completed",
  metadata = { completed_at: "<ISO 8601 timestamp>" }
)

End with:

Run /implement to plan and implement this task.

The pipeline-team persists for use by /implement — editor and reviewer will be spawned into it just-in-time when /implement runs. The session is already in the worktree — /implement does not call EnterWorktree.

describe-task

Invocation

Tool Access

Context Preview

SKILL.md

describe-task

Invocation

Tool Access

Context Preview

SKILL.md

Describe Task

Step 0 — Load code-forge:orchestrator-protocol

Step 1 — Capture the Description

Step 2 — Clarify the Description

Step 3 — Create Pipeline Team, Worktree, Spawn Researcher, and Assign Task

Step 4 — Validate Brief

Step 5 — Emit Result

Similar Skills

Describe Task

Step 0 — Load code-forge:orchestrator-protocol

Step 1 — Capture the Description

Step 2 — Clarify the Description

Step 3 — Create Pipeline Team, Worktree, Spawn Researcher, and Assign Task

Step 4 — Validate Brief

Step 5 — Emit Result

Similar Skills