complex-task-protocol

name	complex-task-protocol
description	Automatic operating protocol for complex agent tasks. Use when work is multi-step, risky, cross-module, orchestration-heavy, or likely to benefit from bounded sidecar help, verification discipline, recovery checkpoints, and durable learning capture.

Complex Task Protocol

Activation

Before meaningful coding work, classify the task as simple or complex.

Activate this protocol when either condition is true:

• at least two ordinary complexity signals are present
• at least one high-signal condition is present

Ordinary complexity signals:

• touches three or more files or two or more modules
• requires investigation plus implementation
• changes architecture, runtime behavior, generated surfaces, install flows, release flows, security, or agent instructions
• likely needs multiple verification commands
• has independent sidecar work such as focused evidence gathering, review, or verification
• the initial focused read does not reveal a clear path

High-signal conditions:

• security-sensitive change
• release, publish, or signoff work
• cross-target agent behavior
• recursive, runtime, orchestration, or subagent behavior
• persistent bug after one direct fix attempt
• explicit user request for complex-task, subagent, learning, or orchestration behavior

Simple Task Bypass

Keep simple work lightweight. Do not announce this protocol or spawn subagents by default for:

• direct questions that do not require code changes
• typo, wording, or single-surface documentation fixes
• obvious one-file edits with a clear verification path
• narrow configuration changes with low blast radius

Execution Map

When the protocol activates, give a concise execution map before broad scanning:

• why the task is complex enough to activate the protocol
• what the main agent will keep on the critical path
• which sidecar work, if any, is independent enough to delegate
• what verification will prove the result
• what recovery threshold will stop unbounded exploration
• whether durable learning capture is likely

Bounded Subagent Use

Consider subagents by default when this protocol is active, but spawn them only when independent work exists.

Default limit: zero to two subagents. Use three only when the user explicitly asks or when three independent tracks are clearly available.

Allowed subagent work:

• focused evidence gathering
• documentation or API verification
• security, correctness, or regression review
• verification while the main agent continues non-overlapping work
• isolated implementation slices with clear file ownership

Disallowed subagent work:

• the main agent's immediate blocking decision
• vague exploration without a concrete question
• duplicate work already assigned elsewhere
• broad scans without a bounded purpose
• edits that overlap another active editor's ownership scope

Keep critical-path decisions and the next blocking task with the main agent.

Subagent Result Schema

Require every sidecar result to include:

• finding or change
• evidence inspected
• files inspected
• files changed, if any
• risks
• confidence
• verification performed, if any

Coding sidecars must also state the behavior changed and known gaps.

Verification

Before claiming completion, run appropriate verification or state what could not be verified. Report:

• checks run
• result
• checks not run
• residual risk

Recovery

Stop unbounded exploration when any recovery trigger appears:

• repeated failed attempts
• unclear root cause after focused inspection
• expanding scope
• context bloat or repeated broad scans

When triggered, produce a concise recovery summary with evidence, attempts, blockers, and the next bounded step. For hard investigations, prefer the recursive investigation flow or token-budget optimizer before adding more prompt context.

Learning Capture

At the end of complex tasks, decide whether anything reusable was learned.

Durable learning categories:

• repository convention
• command or verification recipe
• recurring failure mode
• architecture or runtime decision
• agent tactic that improved outcomes
• target support caveat

Do not persist:

• temporary task state
• obvious facts already documented
• duplicate guidance
• private or user-specific preferences unless explicitly requested
• speculative lessons without evidence

Prefer existing destinations:

• project docs
• runtime task artifacts
• decision records
• observability summaries
• canonical guidance or skill surfaces

Ask before creating a new top-level document when no established destination exists.

References

• .hforge/runtime/agent-brief.md
• .hforge/generated/agent-command-catalog.json
• .hforge/library/skills/token-budget-optimizer/SKILL.md
• .hforge/library/skills/recursive-structured-analysis/SKILL.md
• .hforge/runtime/recursive/language-capabilities.json