Skip to content

amElnagdy/delegate-skills / skills/commandcode-delegate

commandcode-delegate

Verified

Delegate a coding task to the Command Code CLI (`cmd`) as a background implementer, then review its diff and land it yourself. Use this whenever the user wants to hand implementation work to Command Code — phrasings like "have Command Code do X", "delegate this to commandcode", "run it through cmd", or "use Command Code to implement/fix/refactor" — or to run a queue of coding tasks through Command Code while staying the reviewer. DO NOT USE for tasks small enough to do inline, or when the user wants the code written directly without delegating.

references/writing-the-brief.md

View on GitHub
# Writing the brief

A brief is the entire task as Command Code will see it. It runs in a fresh process with **no memory of
your conversation, no access to your prior notes, and no shared context** — only the text you send and
whatever it can read from the working tree (including the repo's own `AGENTS.md`, which it picks up
automatically, and any skills it discovers there).
If a constraint isn't in the brief or discoverable in the repo, it doesn't exist for Command Code. The
single most common failure is a brief that assumes context it doesn't have.

## The shape that works

Command Code responds best to compact, block-structured prompts with XML tags rather than long prose.
State the task, what "done" looks like, how to behave by default, and the few constraints that actually
matter. Add a block only when the task needs it — don't ship empty ceremony.

```xml
<task>
One or two sentences: the concrete job and where it lives. Then the specifics — current state, what to
change, and explicitly what to leave untouched. The "leave untouched" list is what keeps Command Code
from wandering into unrelated refactors.
</task>

<verification_loop>
Run these before finishing and fix anything they surface, don't just report it:
  <the project's real test command>
  <the project's real lint/format command>
  <the project's real build/typecheck command>
Confirm the working tree shows only the intended changes afterward.
</verification_loop>

<action_safety>
Keep changes scoped to the task. No unrelated refactors, renames, or cleanup unless required for
correctness. Do NOT run git add or git commit — the orchestrator commits after reviewing. Leave the
work uncommitted in the working tree.
</action_safety>

<structured_output_contract>
End with a report in this exact shape:
  1. What changed and why
  2. Files touched
  3. Gate outcomes (paste the test/lint counts)
  4. Anything you deviated on, left open, or want a decision on
</structured_output_contract>
```

That four-block skeleton covers most implementation tasks. Reach for the extra blocks when the task
profile calls for them:

- **Debugging / open-ended fixes** — add `<completeness_contract>` (resolve fully, don't stop at the
  first plausible fix) and `<missing_context_gating>` (don't guess missing repo facts; find them or
  state what's unknown).
- **Review / diagnosis (read-only)** — add `<grounding_rules>` (ground every claim in evidence; label
  inferences) and run with `--read-only` so the write, edit, and shell tools stay withheld.
- **Research / recommendations** — add `<research_mode>` (separate observed facts, inferences, open
  questions).

## Path discipline is scope guidance

An implementation run goes out under `--yolo`, which means no filesystem boundary: Command Code can
write anywhere the process can reach, not just under `--cd`. Name the files or directories it may
change, say plainly that everything else is off limits, and keep `<action_safety>` in every
write-capable brief. That is guidance, not a sandbox. A worktree isolates the checkout but does not
contain the process; use a container or another OS-enforced boundary when writes outside the target
tree are unacceptable. `touchedFiles` is only a review aid: it cannot show ignored files or writes
outside the repository.

## `git commit` is not blocked, only forbidden

Sibling delegates can rely on a sandbox refusing to write `.git`. This one cannot: under `--yolo`,
Command Code can commit, so the brief has to tell it not to. Record `HEAD` before dispatch and keep the
"do NOT run git add or git commit" line. If `HEAD` changed, inspect status, staged and unstaged diffs,
and the intervening log first. Only after confirming the whole commit range belongs to the run, use
`git reset --soft <recorded-baseline>` so you can review that range as a diff.

## Discover the real gates — don't hardcode

`<verification_loop>` is only useful if it names the project's *actual* commands. Read the repo's
`AGENTS.md` / `CLAUDE.md` / `Makefile` / `package.json` first and copy the real ones in (`make test`,
`npm run lint`, `cargo test`, `pytest -q`, whatever it is). A brief that says "run the tests" without
naming them gets you an implementer that guesses — or skips.

## Honor the repo's conventions

Command Code reads the repo's `AGENTS.md` automatically, so house rules there (style, forbidden
patterns, commit conventions) already apply. If the project forbids certain things in code — say,
spec/ticket IDs in comments, process language like "MVP"/"for now"/"phase N", or specific test
conventions, whatever the repo's own conventions ban — restate the load-bearing ones in the brief too,
because compliance is only as reliable as what's in front of it.

## One task per brief

Keep each brief to a single, bounded job. "Review this, fix what you find, update the docs, and
suggest a roadmap" produces a muddled run; split it into separate dispatches. One brief → one run →
one commit keeps review and rollback clean, and lets a later task assume the earlier one landed.

Turns are capped (Command Code's own default is 100; `--max-turns` changes it). A brief bundling four
jobs is also the brief most likely to hit that cap and stop mid-way, reported as `stopReason:
max_turns` with a half-finished tree.

## Premises freeze at dispatch

The implementer starts from the brief's facts and there is no steering channel mid-run. Audit the
fact block before sending — ownership, target branch, constraints, anything a judgment call rests
on. If a premise turns out wrong while the run is live, stop the run and re-dispatch a corrected
brief rather than discounting the output afterward; for a write-capable run, inspect the working
tree and reconcile any partial or premise-contaminated edits — keep or revert them — before the
re-dispatch.

## Expect environment preamble in the reply

The final message may carry environment noise on top of your requested report — a banner injected by
the repo's `AGENTS.md`, extra text from an MCP server or skill you have configured locally, taste
notes from Command Code's own learning. That comes from your setup, not a relay defect. The
`<structured_output_contract>` is your defense: ask for a clearly delimited report section so you can
find the real output regardless of what wraps it.

## A worked example

```xml
<task>
In the payments service at services/billing/, the refund path double-charges when a refund is retried
after a network timeout (the idempotency key isn't checked before re-submitting). Make the refund
submission idempotent: check for an existing refund by idempotency key before creating a new one.
Touch only services/billing/refund.py and its tests. Leave the charge path, the API routes, and the
data models untouched, and do not write outside services/billing/.
</task>

<verification_loop>
Run and make green before finishing:
  pytest tests/billing/ -q
  ruff check services/billing/
Confirm git status shows only refund.py and its test file changed.
</verification_loop>

<action_safety>
Scope strictly to the refund idempotency fix. No unrelated refactors. Do NOT git add or commit; leave
changes in the working tree for review.
</action_safety>

<structured_output_contract>
Report: (1) the root cause and your fix, (2) files touched, (3) pytest + ruff outcomes with counts,
(4) anything you left open or want decided.
</structured_output_contract>
```

Send this with `relay.mjs` (see [dispatch-and-poll.md](dispatch-and-poll.md)); review the result and
commit it yourself (see [review-and-land.md](review-and-land.md)).
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall