ucsahinn/agentchef / plugins/agentchef/skills/agent-brief
agent-brief
VerifiedWrite the task brief an orchestrator hands to another agent (subagent, Codex worker, or peer session) and check the handoff that comes back. Use before any delegation that has a goal, a write scope, or acceptance criteria; skip it for a one-line read-only question.
Agent Brief
One fixed shape for every delegated task, so the receiving agent never guesses the goal, the limits, or what "done" means, and the reply can be checked field by field.
When
- Before delegating work that changes files, runs commands, or must meet a stated result. A read-only lookup needs no brief.
- A matched autoVerify routing profile (
security-sensitive,release-or-publish,mcp-connector-change,frontend-ui,data-systems) makes its verifier mandatory once files changed: brief that verifier before reporting done. - If the request is vague or has many steps, first make a plan with
prompt-architectin its plan-only mode, then write the brief from that plan. - If the user asked for a board task, record its write scope there
(
create --write-repo --write-paths) before work starts. Without a board task, list the write scope in the brief only. Never create a board task the user did not ask for.
Team protocol
- Roles: the user approves; the main session plans, briefs, merges, runs every board command, and reports; a coordinator picks its own cataloged workers and merges their handoffs (read-only); a worker does one bounded job.
- Routes: Direct, the main session briefs the specialists the task needs; Team, for a board task, the main session briefs its coordinator, which briefs its own workers. Size the workers per task to the live capacity recommendation (a coordinator is not counted); two levels.
- Workers never spawn. When another role is needed, the worker writes
needs: <role> - <why>under Open questions and the parent decides.
Brief fields
Write each label on its own line as Label: or ## Label, optionally
bilingual (Goal / Hedef:, **Goal** (Hedef):). English or Turkish labels
both parse, and so do numbered or bulleted labels. Write none for an empty
field; never drop a label. A filled-in example is in
references/brief-template.md.
- Goal (Hedef): the outcome for the user in one or two sentences.
- Evidence (Kanıt): what is already known, with commands, paths, and measurements. No guesses presented as facts.
- Write scope (Yazma kapsamı): the repository and paths that may change. Write "read-only" when nothing may change. Two workers never share a path.
- Boundaries (Sınırlar): what must not change or run: other agents' areas, live systems, approvals still needed.
- Done when (Bitti kriteri): checkable acceptance, such as a test, a command's output, or a measured number. It is also the stop condition.
- Return format (Dönüş biçimi): the six handoff fields below, on one line.
- User's words (Kullanıcının özgün cümlesi): the user's request copied verbatim, never paraphrased.
- Environment traps (Ortam tuzakları) and Isolation (İzolasyon) are optional brief fields for shell, runtime, data, or workspace constraints.
Check it before sending:
npm run coordination:board -- brief-check --brief-file brief.md --json
On a board task, store it with brief --task <id> --brief-file brief.md. The
task cannot move to in_progress without an owner and a complete brief, and a
task with a write scope also needs a lease (renew-lease --task <id> --minutes 90)
that no other open task holds on the same paths.
Handoff fields
The receiving agent returns exactly these six, in this order:
- Outcome (Sonuç): what is now true.
- Evidence (Kanıt): the commands run and their results, and paths.
- Changed scope (Değişen kapsam): every file or setting changed, or
none. - Risks (Riskler): what could still be wrong.
- Open questions (Açık sorular): decisions left to the orchestrator or
user, and any
needs: <role>request. - Next verification (Sıradaki doğrulama): the next check worth running.
Handoffs may also include Verdict (Sonuç sınıfı): VERIFIED, REFUTED,
UNMEASURED, or board statuses PASS, WARN, PARTIAL, BLOCKED, FAIL.
Turkish labels and values are accepted. Mutation check (Mutasyon kontrolü)
records changed paths; documentation-only or read-only work uses
none - <reason>. Both are optional in legacy checks and required in strict
checks. An unknown verdict is reported as a warning.
Check it when it comes back:
npm run coordination:board -- handoff-check --handoff-file handoff.md --json
The board CLI checks the six required handoff fields. When Verdict and
Mutation check are also required, inspect them explicitly; strict validation
is available to library consumers as parseHandoff(text, { strict: true }),
not as a board CLI flag.
Merge and verify
- Merge: check each Changed scope against its brief's Write scope, resolve conflicts or ask the user, and rerun every Done-when check on the merged result. A handoff is a report, not proof.
- Verify with an agent that did not do the work: never the owner, its session,
or its coordinator. Pick by work type:
test_verifierfor checks,code_reviewerfor diffs,frontend_verifierfor UI,security_auditorfor security, or the user. Give the verifier the brief and the handoff. - Close a board task in order:
add-evidence,attach-report, resolve any open decision (resolve-handoff), thentransition --status done --verified-by <agent>. If verification fails, renew the lease first, then move it back withtransition --status in_progress --reason "<why>", and update the same brief. A stuck task isblockedwith a reason; unwanted work iscancelled. After three failed attempts, transition the task to blocked withtransition --status blocked --reason "attempt 3/3: ..."and record the unresolved decision withhandoff --decision-needed. - Verifier names are typed by the caller, so the board stops honest mistakes, not a deliberate impersonation.
Rules
- Never put secrets, tokens, or private memory content in a brief; the board refuses text that looks like a credential.
- Keep the user's words verbatim even when the rest is translated.
- One brief per worker. If the scope changes, update that brief instead of sending a second message that contradicts it.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |