iWP Claudy
39a637410c
WordPress plugin rebrand/conventions/remote-CLI patterns, Gitea release workflow, bastille jail provisioning, remote shell quoting safety, server fleet map, delegate brief writing, and verification discipline -- all derived from real incidents this session, plus two skills adapted (MIT license, attributed) from obra/superpowers and andrej-karpathy-skills.
69 lines
3.5 KiB
Markdown
69 lines
3.5 KiB
Markdown
---
|
|
name: delegate-brief-writing
|
|
description: Use when handing a task off to a CLI-based coding delegate (kimi, agy, vibe, codex, or a fresh subagent) that has no memory of the current conversation. Covers what a self-contained brief needs.
|
|
---
|
|
|
|
# Delegate Brief Writing
|
|
|
|
A delegate CLI (kimi, agy, vibe, codex) or a fresh subagent has **zero
|
|
memory** of anything discussed so far — not the goal, not what's already
|
|
been ruled out, not which files matter. Everything it needs has to be in
|
|
the prompt itself.
|
|
|
|
## What a self-contained brief needs
|
|
|
|
1. **Background**: what is being built and why, in enough detail that
|
|
the delegate can make small judgment calls correctly without asking.
|
|
2. **Exact scope boundaries**: what's in scope, and just as important,
|
|
what's explicitly OUT of scope (a delegate that doesn't know a
|
|
boundary exists will happily wander past it).
|
|
3. **Confirmed facts, stated as confirmed** — not "probably" or "should
|
|
be": if you already checked something (a slug mapping, a config
|
|
value, a file's actual current content), say so explicitly and tell
|
|
the delegate not to re-derive it. Re-deriving already-known facts
|
|
wastes the delegate's budget and can introduce a *different*,
|
|
incorrect answer.
|
|
4. **Exact commands/patterns to follow**, not just a description of the
|
|
goal — if there's an established pattern (see e.g. the
|
|
`wordpress-plugin-rebrand` skill), give the exact steps, don't make
|
|
the delegate reinvent the process from a one-line goal statement.
|
|
5. **Credentials handling**: tell the delegate exactly how to read a
|
|
credential (e.g. "read the token fresh from `/path/to/token-file`")
|
|
and explicitly forbid printing/writing it anywhere.
|
|
6. **What to verify before reporting done**, concretely (lint, a specific
|
|
grep, a specific functional test) — see the
|
|
`verification-before-completion` skill.
|
|
7. **Exact report format expected back**, with a length cap. An
|
|
unconstrained delegate report is often much longer than useful.
|
|
|
|
## Wrapper-agent pattern: make it wait for the real result
|
|
|
|
If dispatching via an intermediate "wrapper" agent whose job is to
|
|
invoke the CLI tool and relay the result: **explicitly instruct it to
|
|
run the command synchronously and wait for actual completion before
|
|
ending its turn.** Confirmed real failure mode: a wrapper agent
|
|
repeatedly backgrounded the CLI process itself and ended its own turn
|
|
immediately, producing a stream of "still running, will report back"
|
|
notifications that never actually contained a result — because the
|
|
wrapper's own turn had already ended, it wasn't actually watching
|
|
anything. If this happens, don't keep re-prompting the same wrapper —
|
|
find the actual underlying process directly and monitor it yourself.
|
|
|
|
## Splitting work across multiple parallel delegates
|
|
|
|
When one deliverable naturally splits into N independent pieces (e.g.
|
|
"rebrand these 5 plugins"): do ONE piece yourself (or with one delegate)
|
|
first as a pilot, nail down the exact pattern including any gotchas
|
|
discovered along the way, THEN write the remaining N-1 briefs
|
|
incorporating everything learned from the pilot — including the specific
|
|
mistakes that happened during the pilot and how they were fixed, so the
|
|
parallel delegates don't repeat them. A brief written *after* the pilot
|
|
is meaningfully more reliable than N briefs all written from a cold
|
|
start.
|
|
|
|
## Always re-verify independently afterward
|
|
|
|
See `verification-before-completion`. A delegate's own final report,
|
|
however detailed and confident-sounding, is a claim — re-derive the key
|
|
facts yourself before treating the task as actually done.
|