# Agent orchestrator (HITO 5) -- intent + scope

Fetch when the user asks "que es un agente?", "quiero un agente
que..." , "scheduled job", "background task", "agente automatico",
"que corra mientras duermo".

## Status

Design draft. No agent code shipped yet. CLARIFY-BEFORE-CODE
gates: `docs/HITO_5_AGENT_ORCHESTRATOR_DESIGN.md` lists 10 points
Pablo must answer before slice 1 lands.

If the user asks the brain to create an agent today, the brain
should:

1. Acknowledge agents are designed but not built.
2. Offer the manual interim: a saved CLI script + a doc the user
   keeps in `~/.yujin-forge/scripts/<slug>.md`.
3. Point at the design doc for the long-form plan.
4. Capture the user's intent in a lesson via
   `yujin.lessons.promote` (HITO 6.4) so the design doc can
   absorb the use-case before code lands.

## What an agent will be (when built)

A saved configuration that can run a sequence of NAC-3 verbs +
MCP bridge tools on behalf of the user, with bounded scope,
explicit approval surface, and optional schedule.

Each agent declares:
- `slug`, `name`, `description`, `icon`
- `tier` -- eco / frontier / managed
- `system_prompt`
- `tool_allowlist` (subset of manifest)
- `default_args`
- `trigger` -- manual / cron / event:<entity>:<verb>
- `output_sink` -- chat / pizarron-tab / webhook / none
- `policy_override` -- inherit / auto / request-approval
- `auth_scope` -- which Vault tokens this agent can use
- `quota` -- per-day calls + tokens + cost USD
- `audit_label` -- mandatory free-text on every dispatch row

## Where agents will live

`~/.yujin-forge/agents/` -- one folder per agent slug, with
`definition.json` + `runs/<ts>.json` + `runs/<ts>.audit.jsonl`.
Managed variant adds a `managed_handle.json` with the Workers
KV key.

## What's NEVER on the allowlist

- `yujin.shell.exec` (too broad)
- `yujin.keys.set` / `yujin.keys.delete`
- `yujin.mcp.set-creds`
- `yujin.workflow.set`

Agents cannot rotate credentials, mutate workflow state, or run
arbitrary shell.

## Recommended seed templates (when slice 7 ships)

- `daily-prs` -- list open PRs, summarise in pizarron.
- `ticket-triage` -- triage support inbox, propose tags.
- `brain-matrix-watcher` -- nightly brain matrix run + diff.
- `support-replies` -- draft replies, await approval.
- `lessons-promote` -- auto-promote lessons after N approvals.
- `costs-report` -- weekly cost-meter digest.

## When to point users at the design doc

If a question is structural ("how would the agent talk to my
Slack?", "what's the latency?"), pull `HITO_5_AGENT_ORCHESTRATOR_DESIGN.md`
from disk via `yujin.fs.read-file` + answer from there.

If the question is "I want X agent" the brain captures the
intent + flags it for the design phase.
