singular-particular-space/skills/commissioning-skill/SKILL.md

---
name: commissioning-skill
description: >
  Use this skill whenever a parent (frontier) agent needs to commission a scion
  (small/fast) agent to work within a module. Triggers when assigning tasks to
  subagents, spawning scions, preparing module environments for agent execution,
  or when planning multi-agent task decomposition within a workspace that follows
  the Spore System architecture. Also triggers when the user says "commission a
  scion", "prepare a module for a subagent", "set up spores for", or "equip an
  agent to work on". Use this skill before spawning any scion — it is the
  mechanism that makes the scion's environment correct before execution begins.
---

# Commissioning Skill

The commissioning skill equips a scion agent's environment before task execution.
It crystallizes parent-agent reasoning into token-budgeted spore files so the
scion executes against pre-resolved policy rather than re-deriving it at runtime.

**Core principle**: pay tokens once at commission time. The scion inherits
decisions, not reasoning load.

---

## When to use this skill

Use this skill every time a parent agent is about to spawn a scion into a module.
It runs *before* the scion starts — not during, not after. If a scion is already
running without having been commissioned, stop it, commission properly, then restart.

---

## Inputs required

Before beginning, confirm you have:

- Task description (what the scion needs to accomplish)
- Target module path (where the scion will operate)
- Scion model class (determines token budget — see references/token-budgets.md)
- Access to the module's `SEEDS.md` if it exists

If any of these are missing, ask before proceeding.

---

## The commissioning sequence

Work through these steps in order. Do not skip steps.

### Step 1 — Read SEEDS.md

Navigate to the module root. Check for `SEEDS.md`.

**If SEEDS.md exists**: scan frontmatter entries only (not body). Look for an
entry where `task-class` matches the current task and `status` is `active` or
`provisional`. Do not read entry bodies yet — frontmatter scan only.

**If SEEDS.md does not exist**: proceed to Step 3 (compose path).

```
Match found (active/provisional) → go to Step 2 (select path)
No match / file absent           → go to Step 3 (compose path)
```

---

### Step 2 — Select path (precedent exists)

A seed entry exists for this task class. Use it.

Read the `spore-file` field from the matching seed entry frontmatter. Verify the
referenced spore file exists at that path. If it does not exist (entry is stale),
treat as no-match and proceed to Step 3.

Check the token count of the spore file against the budget for the scion model
class (see references/token-budgets.md). If the file is within budget, proceed
to Step 4. If it exceeds budget, prune before proceeding — see Pruning section.

If the seed entry status is `provisional`, note this. Flag to the parent after
the scion completes its first run — if no escalation occurred on covered decisions,
promote the entry to `active` in SEEDS.md.

---

### Step 3 — Compose path (no precedent)

No matching seed entry exists. Compose a new spore file from first principles.

**3a. Analyze the task and module tool surface**

Read the module SKILL.md if it exists. If no SKILL.md is present, proceed using
the task description and module folder structure as your primary inputs — note
in the seed entry body that no SKILL.md was found and the analysis was based on
folder inspection alone. Identify which tool calls the scion is likely to make
for this task class. Focus on:
- File write/read operations (what paths, what constraints)
- Bash command patterns (what is safe, what needs blocking)
- Output format requirements (what the scion must produce)
- Escalation triggers (what is genuinely novel vs. what is known)

**3b. Reason through the decision surface**

For each likely tool interaction, reason through: what should always be allowed,
what should always be blocked, what requires contextual judgment (spore entry),
and what is fully deterministic (hook candidate). Do this reasoning now, at
commission time. The scion will not do this reasoning.

**3c. Write spore entries**

Write one entry per decision. Follow the entry format exactly — see
references/spore-entry-format.md. Each entry must comply with:

- Maximum 60 tokens per entry (estimate; see token-budgets.md for model-specific guidance)
- One trigger condition
- One outcome (allow / deny / escalate)
- No prose reasoning — reasoning belongs in the seed entry body, not here

**3d. Generate hooks where appropriate**

If the module does not yet have a `hooks/` directory, create it before writing
any hook files. For any decision that is fully deterministic (no contextual
judgment required), generate a hook file in `module/hooks/`. Use Python (stdlib
only) for Python projects or any project without a stated language preference.
Use JavaScript (Node.js, no packages) for TypeScript/JavaScript projects.

See references/hook-protocol.md for the raw protocol, self-contained templates
in both languages, and validation instructions. No external SDK or library is
required — the hook protocol is just stdin JSON in, exit code out.

Reference the hook in the spore entry's `hook:` field. Every hook must pass
both a deny-trigger test and a safe-path test before registration. A spore
that references a faulty hook is worse than no spore.

**3e. Write the spore file**

Write the composed entries to `module/spores/{task-class}-spores.md`. Use the
task class as the filename stem. If a `default-spores.md` already exists and
contains relevant entries, do not duplicate them — reference or inherit instead.

**3f. Write the seed entry**

Write a new entry to `SEEDS.md` at the module root. Status: `provisional`.
Include:
- Frontmatter: `task-class`, `spore-file`, `status`, `deposited`, `supersedes`
- Body: the full reasoning you did in step 3b — why each policy was chosen,
  what edge cases were considered, what would trigger a revision. Write for a
  frontier model reading it later, not for the scion.

See references/seeds-entry-format.md for the full format.

---

### Step 4 — Enforce token budget

Count the tokens in the selected or composed spore file. Compare against the
ceiling for the scion model class (references/token-budgets.md).

If within budget: proceed to Step 5.

If over budget: prune the spore file before proceeding.

**Pruning rules** (apply in this order until within budget):
1. Remove entries marked `superseded` in SEEDS.md
2. Remove entries whose hook has been deleted or rewritten
3. Remove entries whose trigger condition no longer applies to the module's
   current tool surface
4. If still over budget, flag to the parent — do not silently truncate entries
   that are still active. The parent must decide what to deprioritize.

---

### Step 5 — Spawn the scion

Spawn the scion with the following context, in this order (order matters for
prompt caching — stable content first):

```
1. Spore file contents           ← stable; will cache across runs
2. Module SKILL.md               ← stable; will cache across runs
3. Task brief                    ← variable; specific to this run
4. Scoped tool permissions       ← derived from spore entries and task
```

Set the `SCION_SPORE_FILE` environment variable to the absolute path of the
spore file before spawning. The session-start hook reads this variable to load
spore contents into context on startup (see references/hook-patterns.md).

Declare the inheritance chain explicitly. If the scion operates in a component
subfolder, state which spore files apply and in what order. Do not rely on
implicit folder inheritance.

Do not give the scion access to SEEDS.md. SEEDS.md is parent-readable only.
Do not give the scion access to the commissioning skill itself.

---

## Escalation handling

When the scion escalates a novel situation to the parent, handle it in two phases:

**Phase 1 — immediate resolution** (blocking; scion waits): reason through the
novel situation and return a direct resolution to the scion so it can continue
its task. Do not make the scion wait for spore deposition — unblocking the scion
is the priority.

**Phase 2 — spore deposit** (after the scion is unblocked): add a new spore
entry to the relevant spore file, add or update the seed entry in SEEDS.md with
status `provisional`, and generate a hook if the decision is deterministic. This
can happen while the scion continues executing.

The next scion to face the same situation encounters pre-resolved policy and
never needs to escalate. The compound loop closes: each novel escalation becomes
future policy at zero marginal cost per repeat encounter.

---

## Pruning vs. superseding

**Pruning** removes a spore entry from the file (reduces token count).
Use when the trigger condition no longer applies.

**Superseding** marks an old seed entry as `superseded` and creates a new one.
Use when the policy has changed but the trigger condition still applies.

Pruned entries disappear from the spore file. Superseded entries remain in
SEEDS.md for audit but are skipped during routing. When you supersede, set
`supersedes: path/to/old-spore-file` in the new seed entry's frontmatter.

---

## Component subfolder scions

A scion operating in a component subfolder (`module/component-x/`) should
receive only the spore file relevant to its component, not the full module spore
file. The commissioning skill selects or composes at the component level.

SEEDS.md is never placed in component subfolders. All seed entries for a module,
including component-level decisions, live at the module root SEEDS.md. The
frontmatter `task-class` field can use a namespaced convention to distinguish:
`task-class: component-x/annotator`.

---

## Reference files

Read these when you need detail on a specific part of the workflow:

- `references/spore-entry-format.md` — full spore entry schema and examples
- `references/seeds-entry-format.md` — full seed entry schema and examples
- `references/token-budgets.md` — per-model token ceilings and rationale
- `references/hook-protocol.md` — raw hook protocol, stdlib templates (Python + JS), validation

---

## What good commissioning looks like

A well-commissioned scion:
- Receives a spore file that fits comfortably within its model class's token budget
- Has hooks pre-installed for all fully deterministic decisions
- Never needs to reason about whether to write to a `.env` file, what output
  format to use, or when to escalate — those decisions are already made
- Escalates only genuinely novel situations, not recurrent known decisions
- Completes its task faster and cheaper than an uncommissioned scion would

A poorly commissioned scion receives either too much context (bloated spore file,
context rot risk) or too little (forced to re-derive known decisions, burning
tokens on settled policy).

The goal is a scion that is maximally fast and focused because its environment
has already done the thinking.