complex-task-protocol

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