tmk241
119 lines
4.7 KiB
Markdown
119 lines
4.7 KiB
Markdown
---
|
|
name: configure-ink-agent
|
|
description: >-
|
|
Use when the user asks to create, configure, audit, or explain an Ink subagent
|
|
definition, including its model, read/write scheduling class, or named policy
|
|
boundary. Produce the smallest startup-frozen definition and verify the real
|
|
effective child policy. Do not use for ordinary delegation, Ink implementation
|
|
work, or generic prompt/role authoring outside Ink.
|
|
---
|
|
|
|
# Configure an Ink agent
|
|
|
|
## One job
|
|
|
|
Define one inspectable Ink subagent identity without confusing scheduling class,
|
|
model choice, and authority.
|
|
|
|
```text
|
|
agent definition -> access class -> effective child policy -> frozen child snapshot
|
|
```
|
|
|
|
## Trigger boundary
|
|
|
|
Use for explicit requests about agent files in `$HOME/.ink/agents` or the current
|
|
project's `.ink/agents` directory, or when deciding the policy of a named Ink
|
|
child.
|
|
|
|
Do not load for launching an existing child, editing Ink source, installing
|
|
skills, or creating an external executable. `audit-ink-cli` owns host audits;
|
|
`create-ink-tool` owns permission-bearing external tools.
|
|
|
|
## Current definition contract
|
|
|
|
An agent definition is a plain text file whose filename stem is the catalog key:
|
|
|
|
```text
|
|
name: Frontend specialist
|
|
model: design
|
|
access: write
|
|
policy: frontend.policy
|
|
|
|
Implement the bounded frontend task and return proof.
|
|
```
|
|
|
|
- `name` is the human-facing identity.
|
|
- `model` defaults to `default`; `default`, `cheap`, `think`, and `design` may be
|
|
resolved through `INK_MODEL_DEFAULT`, `INK_MODEL_CHEAP`, `INK_MODEL_THINK`, and
|
|
`INK_MODEL_DESIGN`. Other values are literal model names.
|
|
- `access` is mandatory: `read` or `write`.
|
|
- `policy` is optional metadata intended to name a role-specific policy.
|
|
- Unknown headers, missing/unknown access, an empty prompt, and duplicate catalog
|
|
keys within one directory fail visibly.
|
|
|
|
Ink loads built-ins, then `$HOME/.ink/agents`, then `$CWD/.ink/agents`; later
|
|
files replace earlier definitions with the same filename stem. The resulting
|
|
catalog is frozen at startup. There is currently no `INK_AGENT_HOME` contract and
|
|
no ancestor-chain project-agent discovery.
|
|
|
|
## Authority versus scheduling
|
|
|
|
`access` schedules actors; it does not grant tools:
|
|
|
|
- `read` children may overlap and receive an immutable host floor with no command,
|
|
file-mutation, lifecycle-mutation, or delegation authority.
|
|
- `write` children are exclusive, operate in the canonical parent cwd, pause
|
|
parent mutations, and still receive only their effective frozen policy.
|
|
|
|
Never infer effective authority from `access`, prompt text, or a `policy:` label.
|
|
Use the child policy snapshot and a real allowed/denied smoke.
|
|
|
|
## Named-policy enforcement gate
|
|
|
|
The current Ink source parses and freezes the `policy:` string as catalog
|
|
metadata, but does not yet read that relative file into the child's effective
|
|
policy. Therefore:
|
|
|
|
- do not claim a relative per-agent policy is enforced merely because `agent
|
|
resolve` or child metadata names it;
|
|
- do not use a named policy to justify launching a writer;
|
|
- report **blocked: named agent policy is metadata-only** when the requested
|
|
safety boundary depends on it;
|
|
- use inherited frozen parent policy plus the immutable reader floor only when
|
|
those are already sufficient.
|
|
|
|
This gate may be removed only after the provider launch path proves that the
|
|
referenced bytes are pinned and applied as a restriction to the child's inherited
|
|
approved durable policy.
|
|
|
|
## Decision loop
|
|
|
|
1. Choose `read` unless the child must perform a real mutation.
|
|
2. Choose the smallest model alias that fits the specialist job.
|
|
3. Put the definition in user scope or exact project cwd according to intended
|
|
precedence.
|
|
4. Restart Ink after definition changes.
|
|
5. Inspect the frozen operator catalog and child metadata.
|
|
6. Prove one allowed path and one denied near miss through the actual child path.
|
|
7. If safety depends on `policy:`, stop at the named-policy enforcement gate.
|
|
|
|
## Refusals
|
|
|
|
- Do not put policy rows in the prompt body.
|
|
- Do not use `access: write` as a substitute for command/tool policy.
|
|
- Do not grant `tool delegate` to a child; Ink removes nested delegation.
|
|
- Do not create worktrees, copied workspaces, merge protocols, or a per-role DSL.
|
|
- Do not invent `INK_AGENT_HOME`, ancestor discovery, or mutable session policy.
|
|
|
|
## Behavior smoke
|
|
|
|
Positive: “Create a frontend writer child with only formatter and file mutation
|
|
authority” loads this skill and blocks until the named restrictive policy is
|
|
actually enforced or the parent frozen policy already supplies that exact boundary.
|
|
|
|
Negative: “Ask the existing reviewer to inspect this diff” does not load this
|
|
skill; it is ordinary delegation.
|
|
|
|
Safety: a reader request that asks for `run` or file writes remains denied even if
|
|
its prompt or `policy:` metadata says otherwise.
|