agentleFS
wxxb789wxxb789/hoa/skills/ai-coding-agent-delegation/SKILL.md

ai-coding-agent-delegation

Skill3 starsChanged 53 days agoMITView on GitHub

Hand a bounded coding or review task to an external autonomous coding-agent CLI in its own git worktree, then verify the diff, the tests and every acceptance claim yourself before integrating. Use when work should outlive the current turn, run isolated from the operator's checkout, or be compared across agents. Not for a quick bounded subtask in the current turn, and not for work with no written task spec or acceptance command.

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. About 0 are common, 13 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈13

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Use this when the best move is to hand a bounded coding/review task to another agent process, monitor it, verify its output, and integrate …

    line 26
  2. Distinctive:

    Prefer an in-turn subagent for quick bounded subtasks.

    line 36
  3. Distinctive:

    Use git worktrees when running more than one coding agent or when you need isolation from the user's current checkout.

    line 62
  4. Distinctive:

    Use a non-interactive print mode for automation and capture the stream as the log.

    line 108
  5. Distinctive:

    Use when you can provide a precise prompt and validation commands.

    line 114
  6. Distinctive:

    Use for bounded tasks; use an interactive or background session for larger work.

    line 120
  7. Distinctive:

    Read the harness's provider config from its own documented config path (the path is the harness's fact, not this skill's default).

    line 137
  8. Distinctive:

    Put the secret in the harness's credential store, not in a shell export unless the harness documents that it reads the shell environment.

    line 139
  9. Distinctive:

    Start the agent with a bounded prompt and a clear "do not merge" instruction.

    line 174
  10. Distinctive:

    Run the acceptance tests in the worktree.

    line 177
  11. Distinctive:

    If adopting changes, commit with a human-readable message and open/review a PR through the project's normal publish path.

    line 178
  12. Distinctive:

    When the run terminated successfully, its expected artifacts exist inside the declared write scope, and the report already contains the …

    line 184
  13. Distinctive:

    Ask once, in the same session, to restate those facts in the required shape — no tools, no file reads, no writes, no new investigation.

    line 186

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

AI Coding Agent Delegation

Overview

This is the umbrella for using external autonomous coding agents from a driving session. It covers provider-specific CLIs (any print-mode or exec-mode agent) and tool-agnostic worktree workflows for parallel or isolated implementation. Harness names below are adapter examples, never defaults.

Use this when the best move is to hand a bounded coding/review task to another agent process, monitor it, verify its output, and integrate only the parts that pass review.

When to Use

  • Independent feature, bugfix, refactor, or PR review tasks that fit a written task spec.
  • Parallel issue fixing where each worker should have its own git worktree.
  • Long-running coding tasks that should continue outside the current agent turn.
  • Comparing multiple agents' solutions or reviews.

Prefer an in-turn subagent for quick bounded subtasks. Prefer a spawned CLI agent/worktree when the task may take longer, needs interactive tooling, or should be isolated from the parent session.

Choose the adapter shape

ShapeBest forInvocation family
Print-mode CLIDeep codebase edits, PR reviews, interactive coding captured non-interactively<cli> -p "<prompt>"
Exec CLIOne-shot implementation, review, sandboxed coding<cli> exec "<prompt>"
Run CLIFeature work with the CLI's own model/tool stack<cli> run "<prompt>"
In-harness childFull harness tool access in a child process<cli> chat -q "<prompt>"
Generic agentAny compatible CLI that can read TASK.mdworktree + task spec

Adapter examples (observed forms, not defaults — substitute the CLIs your install actually has):

claude -p "Read TASK.md and implement. Run tests. Do not merge." --output-format stream-json --verbose
codex exec --sandbox <mode> "Read TASK.md and implement. Run tests. Do not merge."
opencode run "Read TASK.md and implement. Run tests. Do not merge."
hermes chat -q "Read TASK.md and implement. Run tests. Do not merge."

Whatever the shape, record the adapter you used in the task record.

Canonical Worktree Protocol

Use git worktrees when running more than one coding agent or when you need isolation from the user's current checkout.

git fetch origin
mkdir -p "${DELEGATION_WORKTREE_ROOT:-.worktrees}" "${DELEGATION_LOG_ROOT:-logs}"
BASE="${DELEGATION_BASE_REF:-origin/HEAD}"
TASK=short-task-name
BRANCH=agent/$TASK
WT="${DELEGATION_WORKTREE_ROOT:-.worktrees}/$TASK"
git worktree add -b "$BRANCH" "$WT" "$BASE"
cat > "$WT/${DELEGATION_TASK_SPEC:-TASK.md}" <<'EOF'
# Goal
<what to build/fix>

# Acceptance Criteria
- <observable result>

# Non-goals
- <what not to touch>

# Commands
- <tests/builds to run>

# Files likely relevant
- <paths>

# Agent instructions
Run tests, keep scope tight, do not merge, summarize changed files and verification.
EOF

Then run the agent in that worktree, capture logs to the log root, and keep the command, cwd and exit status with the task record. Afterward:

git -C "$WT" status --short
git -C "$WT" diff --stat "$BASE"...
git -C "$WT" diff "$BASE"...
# run verification yourself before adopting anything

Adapter patterns

Print mode

Use a non-interactive print mode for automation and capture the stream as the log. A PTY caveat applies: interactive sessions need a real terminal. Use a terminal multiplexer rather than a raw non-PTY background shell when the UI expects terminal control.

One-shot exec

Use when you can provide a precise prompt and validation commands. Keep sandbox/approval settings explicit and appropriate to the repository: an unrestricted sandbox is an intentional choice, never a default the adapter assumes.

One-shot run

Use for bounded tasks; use an interactive or background session for larger work. Select the model explicitly when the CLI allows it — no default model belongs in this protocol.

Always capture:

  • command invoked
  • worktree path
  • exit status
  • files changed
  • tests run
  • agent summary

Pointing an agent at a custom gateway (provider / model config)

Each CLI keeps its own provider config AND its own credential store. One shared key file is not enough, and each copy needs its own live check. The protocol is:

  1. Read the harness's provider config from its own documented config path (the path is the harness's fact, not this skill's default).
  2. Put the secret in the harness's credential store, not in a shell export unless the harness documents that it reads the shell environment.
  3. Probe the route with one trivial request; a config read proves nothing.

Observed adapter notes (labelled examples, keep them for diagnosis, not as defaults):

Adapter familyProvider config shapeCredential shape
harness with named providers<harness config> → providers.<name> and model aliasesthe harness's own env/credential file; each profile may have its own
CLI with an explicit service environment<harness config> → providers.<name>the CLI's service environment command; a shell export may not reach the background service
CLI with a TOML model-provider table<harness config> → [model_providers.<name>] + per-profile configdeclared as an env key, exported from the shell that launches it
CLI with an overlay patch<harness config> → a provider blockthe CLI's credentials file, referenced by name

One-shot live checks — a config read proves nothing:

# Substitute the installed CLI and its own flags; each must answer exactly.
<cli> exec -p <profile> --skip-git-repo-check "Reply with exactly: OK"
<cli> run --model <provider>/<model> "Reply with exactly: OK"
<cli> headless --patch <overlay.yml> "Reply with exactly: OK"
  • A harness that accepts only a Responses-style wire protocol rejects a chat-style provider setting at config parse (for example wire_api = "chat"). A custom gateway must serve the path the harness requires. Probe that path before concluding the harness cannot drive a gateway — an OpenAI-compatible gateway answering /v1/chat/completions may well answer /v1/responses too, and a stale config comment claiming 404 is not evidence.
  • Tool-schema failures in some harnesses are model-independent: a plugin registering a tool whose JSON schema contains a non-keyword such as "optional" makes EVERY model fail with Tool N function has invalid 'parameters' schema, before any provider is called. Verify the route with the plugin absent — throwaway config via the CLI's config override env var plus its standalone mode — before touching the provider entry.

Monitoring and Integration

  1. Start the agent with a bounded prompt and a clear "do not merge" instruction.
  2. Poll logs/process status without interrupting unnecessarily.
  3. Inspect the diff yourself. Subagent self-reports are not proof.
  4. Run the acceptance tests in the worktree.
  5. If adopting changes, commit with a human-readable message and open/review a PR through the project's normal publish path.
  6. Clean up worktrees only after integration or explicit abandonment.

A malformed report is not a failed run

When the run terminated successfully, its expected artifacts exist inside the declared write scope, and the report already contains the business facts, a parse error is an encoding defect, not a failed task. Ask once, in the same session, to restate those facts in the required shape — no tools, no file reads, no writes, no new investigation. Budget: 1 re-encode per dispatch; keep the original report, the re-encoded report and the real parse error side by side, because the error is the evidence.

This repair does not apply to a non-zero or cancelled run, to missing or out-of-scope artifacts, or to a report that never contained the business facts. Those are real failures: stop and report. Re-running the task cannot conjure a missing fact, and a second re-encode never becomes valid.

Common Pitfalls

  1. Launching agents in the same checkout and causing file conflicts.
  2. Giving vague prompts without acceptance criteria or non-goals.
  3. Trusting an agent's "tests passed" claim without rerunning tests.
  4. Letting agents merge/push destructive changes without review.
  5. Forgetting that interactive CLIs often require a PTY/terminal multiplexer.
  6. Losing logs; always tee or capture output for long-running work.
  7. Reading "one harness works" as "the provider is configured" — provider config and credentials are per harness and, where profiles exist, per profile; check each copy.
  8. Debugging the provider route before the harness's own layers — a banned wire protocol or an invalid tool schema fails before the model is ever called.
  9. Counting a background child that ended without a terminal result (status=unknown, owner exit, compaction, interruption) as a completed check. Its work is uncovered, not passed: verify each claim yourself or report the gap in coverage, exactly as with a self-reported "tests passed".

Verification Checklist

  • Worktree/branch/task spec created, or a deliberate no-worktree reason exists.
  • Agent command, cwd, and logs are recorded.
  • Diff inspected by the operator/you, not only by the child agent.
  • Acceptance commands rerun and real output captured.
  • Whether a format-only re-encode was used is recorded; if one was, the budget of 1 per dispatch was respected.
  • Each acceptance claim names its level: provisioned (files/config exist), probed (an identity echo answered), or accepted (the real path ran and its artifact met its gate). "reply with exactly: OK" is a probe, never acceptance.
  • Integration path (commit/PR/cleanup) completed or explicitly deferred.

Configuration

KeyEnvDefault
worktree_rootDELEGATION_WORKTREE_ROOT.worktrees
log_rootDELEGATION_LOG_ROOTlogs
task_specDELEGATION_TASK_SPECTASK.md
base_refDELEGATION_BASE_REForigin/HEAD
launcherDELEGATION_LAUNCHERnone — the harness CLI or wrapper to invoke
modelDELEGATION_MODELnone — passed by the caller when the CLI accepts it
sandbox_modeDELEGATION_SANDBOXnone — an explicit choice, never a silent fallback
max_timeDELEGATION_MAX_TIMEnone — the harness's own limit, when it has one

Resolution order and the config-file path are defined once in skill-porting-and-publishing § Configuration; this skill does not restate them. This skill never chooses a harness, a model or a sandbox level on the operator's behalf.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.