Initial commit — Singular Particular Space v1

Homepage (site/index.html): integration-v14 promoted, Writings section integrated with 33 pieces clustered by type (stories/essays/miscellany), Writings welcome lightbox, content frame at 98% opacity. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-27 12:09:22 +02:00
commit 5422131782
359 changed files with 117437 additions and 0 deletions
--- a/skills/commissioning-skill/SKILL.md
+++ b/skills/commissioning-skill/SKILL.md
@@ -0,0 +1,270 @@
+---
+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.