From code-forge
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.
How this skill is triggered — by the user, by Claude, or both
Slash command
/code-forge:describe-taskThis skill is limited to the following tools:
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.
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.
Reference: code-forge:orchestrator-protocol · code-forge:researcher-protocol · task-brief-format
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.
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:
Capture the user's answer as <DESCRIPTION>. Proceed to Step 2.
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):
Q2 — Done condition (include only if description lacks a concrete outcome):
Q3 — Codebase focus (include only if description is vague about location):
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.
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.
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:
"failure": read brief.md for the Failure Report content, surface it verbatim, and stop."escalation": read brief.md for the NEEDS_ESCALATION content, surface it verbatim, and stop."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.
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
/implementto 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.
Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub techyshishy/code-forge --plugin code-forge