singular-particular-space/SPORE_SYSTEM_SPEC_v0.2.md

# The Spore System — Integrated Specification v0.2

**Status**: Draft. Supersedes v0.1.
Validated claims marked ✓. Working hypotheses marked ~.

*Authors: human + Claude Sonnet 4.6 — drafted 2026-03-20*

---

## Overview

The Spore System is a context architecture for multi-agent AI projects. It separates
reasoning from execution by crystallizing parent-agent decisions into structured,
token-budgeted files that smaller scion agents inherit without re-deriving.

The core principle: **pay tokens once at commission time. Make every subsequent
run cheaper, faster, and more deterministic.**

The system operates across three scopes — workspace, module, and component — with
distinct file types at each level serving distinct purposes and audiences.

---

## Design principles

**Signal density over verbosity.** Compressed context can outperform uncompressed
context on smaller models (CompLLM, 2025). ✓ The optimization direction — denser,
more atomic, zero noise — is monotonically beneficial across all model tiers. Small
models require it to perform reliably. Frontier models benefit from it economically.

**Separate reasoning from execution.** The parent reasons. The scion executes. These
are not the same cognitive act and should not be performed by the same agent in the
same context.

**Accumulation over regeneration.** Spore files grow over project lifetime. Each
novel decision becomes future policy at zero marginal cost per repeat encounter.

**Scope discipline.** Each file type has a defined audience and a defined scope.
Files do not bleed across scope boundaries.

---

## Layer hierarchy

```
workspace root/
├── AGENTS.md                    ← project identity, strategy, broad goals
├── CLAUDE.md / GEMINI.md        ← agent-specific global behavior
├── commissioning-skill/         ← parent capability; not for scions
│
├── module-a/
│   ├── SKILL.md                 ← how to work in this module
│   ├── SEEDS.md                 ← parent-readable index and provenance log
│   ├── spores/
│   │   ├── annotator-spores.md  ← task-specific crystallized decisions
│   │   ├── validator-spores.md
│   │   └── default-spores.md    ← module-wide fallback
│   ├── hooks/
│   │   ├── env-guard.py
│   │   └── output-validator.py
│   │
│   └── component-x/             ← sub-module; more specialized
│       ├── SKILL.md             ← optional; component-specific capability
│       └── spores/
│           └── annotator-spores.md  ← narrower still; component-scoped
│
└── module-b/
    ├── SKILL.md
    ├── SEEDS.md
    ├── spores/
    └── hooks/
```

---

## File types

### AGENTS.md (CLAUDE.md / GEMINI.md)

**Scope**: workspace root
**Audience**: parent (frontier) agent
**Purpose**: project identity, strategy, goals, commissioning skill declaration

This is the parent agent's home context. It describes what the project is, what
it is trying to achieve, and declares the commissioning skill as the mechanism
for spawning and equipping scions.

Not token-constrained — the parent model can handle the load. Should be well-structured
to avoid the bias-injection risk of long, heavily reasoned documents.

---

### SKILL.md

**Scope**: module or component level
**Audience**: any agent operating in this module
**Purpose**: procedural capability — how to do things here

Skills describe *how* to perform tasks within a module's context: tool usage patterns,
conventions, output formats, constraints specific to this codebase. They are
capability declarations, not decision logs.

A module SKILL.md and a component SKILL.md can coexist. A component's skill is
more specialized; the parent commissioning into that component reads both.

---

### SEEDS.md

**Scope**: module root only — one per module, never in subfolders
**Audience**: parent (frontier) agent exclusively
**Purpose**: index of existing spore files + provenance and reasoning log

SEEDS.md serves two functions simultaneously:

1. **Routing index**: the commissioning skill scans SEEDS.md frontmatter to
   determine whether a matching spore file exists for the current task class.
   If it does, select. If it does not, compose.

2. **Provenance log**: the body of each entry records the reasoning the parent
   did before compressing a decision into a spore. This is what the parent reads
   when reviewing, updating, or deprecating a spore.

SEEDS.md is not token-constrained the same way spore files are — it is read by
the frontier model. However, dense prior reasoning can anchor a frontier model's
outputs in ways that resist correction (bias-injection risk). Structure mitigates
this: the parent attends to frontmatter first and reaches into the body only
deliberately, when it needs the reasoning behind a specific decision.

SEEDS.md is **mutable**. Entries are updated in place when decisions are revised.
Unlike spore files, it is not append-only — outdated entries should be superseded
rather than accumulated, to prevent the bloat that would otherwise degrade the
frontier model's context.

#### Entry format

```yaml
---
task-class: annotator
spore-file: spores/annotator-spores.md
status: active          # active | superseded | provisional
deposited: 2026-03-20
supersedes: null        # spore-file this replaced, if any
---

## Reasoning

[Parent agent's reasoning log for this decision class. Why this policy was chosen,
what edge cases were considered, what situations would trigger a revision.
Written for the frontier model, not for scions. No token constraint — optimize
for completeness and correctness here.]

## Revision triggers

- [Condition that would make this policy stale]
- [Condition that would require a more specific spore]
```

**Status lifecycle** ~

| Status | Meaning | Commissioning action |
|---|---|---|
| `active` | Current, use as-is | Select corresponding spore file |
| `provisional` | New, unvalidated in production | Select but flag for review after first run |
| `superseded` | Replaced by newer entry | Skip; read superseding entry instead |

~ Status transition triggers are not fully specified. A provisional entry should
be marked active after successful scion runs against it. Superseded entries should
be retained for audit purposes but skipped during routing. The number of successful
runs required to promote provisional → active is a project-level decision.

---

### Task-specific spore files

**Scope**: `module/spores/` or `module/component/spores/`
**Audience**: scion (small/fast) agents
**Purpose**: crystallized, executable decisions for a specific task class

A spore file contains only what a specific scion needs to accomplish a specific
class of task. Nothing more. Each entry encodes one pre-resolved policy decision.

Scions do not reason about what a spore contains. They execute against it.

#### Naming convention

```
annotator-spores.md       ← for annotation task scions
validator-spores.md       ← for validation task scions
transformer-spores.md     ← for transformation task scions
reviewer-spores.md        ← for review task scions
default-spores.md         ← module-wide fallback; used when no task-specific file exists
```

The commissioning skill selects the file by task class name. The name is the
routing key — keep it precise and consistent across modules.

#### Entry format

Each entry is atomic. No prose reasoning. No multi-sentence explanations.
One trigger condition. One outcome.

```yaml
---
spore: env-file-write-guard
task-class: annotator
scion-model: haiku-4.5
deposited: 2026-03-20
hook: hooks/env-guard.py     # nil if policy-only; no compiled hook
---
policy: deny writes to *.env, secrets.json, id_rsa
trigger: PreToolUse · tool=Write · file_path matches sensitive-file pattern
on-match: deny
on-novel: escalate to parent
```

**Hard constraints per entry** ~

| Constraint | Value | Status |
|---|---|---|
| Maximum tokens per entry | 60 | ~ estimate; test per model class |
| Explanatory prose | none | ✓ |
| Trigger conditions | one | ✓ |
| Outcomes | one | ✓ |
| Hook reference | optional | ✓ |

#### Token budget by scion model class ~

The parent sets the file-level budget when commissioning, based on who will
read it. These are working estimates derived from context rot research (Chroma,
2025; Liu et al., 2024). Not empirically tested against this architecture.
Measure and adjust.

| Scion model class | Nominal window | Spore file ceiling |
|---|---|---|
| Haiku 4.5 | 200K | 600 tokens |
| Gemini 2.5 Flash | 1M | 800 tokens |
| Sonnet-class scion | 200K | 1,200 tokens |

The ceiling applies to the full spore file, not per entry. As entries accumulate
and approach the ceiling, the commissioning skill is responsible for pruning
superseded entries before depositing new ones.

**Why density is a quality constraint, not just a cost constraint** ✓

Context rot is empirically universal — every model degrades before its nominal
window limit, and degradation occurs well before the limit is reached. Smaller
models degrade faster. A dense, denoised 500-token spore file will produce better
scion outputs than a verbose 2,000-token one on Haiku-class models — not just
cheaper outputs. Signal density is optimized for the scion; a frontier parent
reading the same file benefits economically from the same property.

---

### hooks/

**Scope**: module level (shared across task classes in the module)
**Audience**: Claude Code hook runtime; executes outside the LLM entirely
**Purpose**: deterministic pre-compiled policy; zero token cost at execution time

Hooks are compiled from spore decisions where the policy is fully deterministic
and requires no contextual judgment. They fire on Claude Code lifecycle events
(`PreToolUse`, `PostToolUse`, `SessionStart`, etc.) before the scion ever reasons
about the situation.

The hook runtime is provided by `cchooks` (Python SDK). Every hook should have
a corresponding spore entry for provenance. Not every spore requires a hook —
decisions that need contextual interpretation remain in the spore file only.

| Layer | What it is | Token cost | Use when |
|---|---|---|---|
| Spore entry | Declared policy | Low (loaded into context) | Policy needs scion interpretation |
| Hook file | Compiled policy | Zero (pre-LLM execution) | Policy is fully deterministic |

---

## The commissioning skill

**Location**: workspace root, alongside AGENTS.md
**Audience**: parent agent only; not accessible to scions
**Purpose**: assemble and equip a scion's environment before task execution

The commissioning skill is the mechanism that makes the system function. It is
invoked by the parent during task planning and performs the following sequence:

```
1. Identify task class and target module
2. Identify scion model class (determines token budget)
3. Read module SEEDS.md frontmatter
4. If matching seed entry (status: active or provisional) → select spore file
   Else → compose new spore file from first principles:
       a. Analyze task and module tool surface
       b. Reason through decision surface for likely tool calls
       c. Generate spore entries (max 60 tokens each) ~
       d. Generate hook files via cchooks where policy is deterministic
       e. Validate hook correctness before registering
       f. Write new seed entry to SEEDS.md (status: provisional)
       g. Write new spore file to spores/
5. Enforce token budget: count tokens in spore file; prune if at ceiling
6. Spawn scion with: task brief + spore file path + scoped tool permissions
```

The commissioning skill SKILL.md is a companion document to this spec and
should be drafted separately.

---

## Lifecycle summary

### Accumulation (spore files)

Spore files are **append-only**. They grow over project lifetime as novel
decisions are encountered and resolved. Each commissioning cycle that encounters
a genuinely new situation deposits a new entry. Known situations are already
present — zero tokens spent re-deriving them.

### Mutation (SEEDS.md)

SEEDS.md is **mutable**. Entries are updated in place when decisions are revised.
Old entries are marked `superseded`, not deleted — retained for audit but skipped
during routing.

### Pruning (spore files)

Pruning is triggered when a spore file approaches its token ceiling or when a
module refactor changes the tool surface. The parent (via the commissioning skill)
is responsible for pruning. Prune when:

- A trigger condition no longer applies (tool removed or renamed)
- A more general spore supersedes a specific one
- The corresponding hook file has been deleted or rewritten
- An entry is marked `superseded` in SEEDS.md

### Escalation (the compound loop)

When a scion encounters a situation not covered by any spore and not intercepted
by a hook, it escalates to the parent. The parent reasons, resolves, deposits a
new seed entry and a new spore entry, and optionally generates a new hook. The
next scion to face the same situation encounters pre-resolved policy. The system
improves with every novel encounter.

```
Novel situation encountered by scion
    → escalates to parent
    → parent reasons (token cost: paid once)
    → new seed entry deposited (provisional)
    → new spore entry deposited
    → hook generated if deterministic
    → future scions: zero tokens on same class of decision
```

---

## Subfolder delegation

Spore files at the module root handle module-wide decisions. Component subfolders
can hold their own `spores/` directory for decisions scoped to that component —
narrower trigger conditions, more specialized context, potentially a different
scion model class.

SEEDS.md does **not** appear in subfolders. All provenance lives at the module
root where the parent has full visibility. The commissioning skill reads module
SEEDS.md for the full picture, then selects or composes component-level spore
files as needed.

A scion operating inside a component inherits only the spore file it was
commissioned with. It does not automatically inherit the module-level spore file.
Inheritance is declared explicitly by the commissioning skill at spawn time —
not implicit from folder position.

---

## Relationship to prompt caching ✓

Spore files are near-perfect caching targets:

- Change slowly (append-only, infrequent updates)
- Loaded at the start of the scion's context
- Identical across all scion runs of the same task class in the same module

Anthropic's prompt caching costs 10% of base input token price on cache hits.
A stable spore file achieves near-100% cache hit rate across all runs in its
task class. The token cost of the file is effectively paid once.

Spore files should be placed early in the scion's context to maximize cache
prefix reuse. The commissioning skill is responsible for context ordering at
scion spawn time.

---

## What each layer answers

| Layer | File | Question answered |
|---|---|---|
| Workspace | AGENTS.md | What are we building and why? |
| Workspace | Commissioning skill | How do we equip and spawn scions? |
| Module | SKILL.md | How do we work in this module? |
| Module | SEEDS.md | What have we already decided, and why? |
| Module / Component | `*-spores.md` | What should the scion do in this situation? |
| Module | `hooks/` | What fires before the scion reasons at all? |

---

## Open questions

**1. Token budget empirics** ~
The per-model ceilings and per-entry 60-token limit are estimates derived from
context rot research. The correct approach is to measure scion task success rate
as a function of spore file size for each model class, then set ceilings at the
observed inflection point. This should be the first empirical work done against
this architecture.

**2. Status transition triggers** ~
The conditions under which a provisional entry becomes active are not defined.
A reasonable default: promote to active after N successful scion runs without
escalation on covered decision classes. N is a project-level decision.

**3. Concurrent commissioning** — out of scope v0.2
If two parent agents commission into the same module concurrently, last-write-wins
on both SEEDS.md and spore files. This is fragile. A file-lock or merge strategy
is needed for production multi-parent scenarios. Deferred to v0.3.

**4. Cross-module spore inheritance** — out of scope v0.2
If a scion operates across module boundaries, which spore file applies? This spec
assumes single-module scope for all scion tasks. Deferred.

**5. Hook validation** ~
A spore that references a faulty hook is worse than no spore. The commissioning
skill needs a validation step (run the hook against a test fixture) before
registering the entry. The validation approach is not specified here.

**6. Format portability** ~
The YAML frontmatter format is designed for Claude Code. Whether the same format
is legible to Gemini CLI scions without modification is untested.

---

## Validation status summary

| Claim | Status | Source |
|---|---|---|
| Context rot degrades all models before nominal window limit | ✓ | Chroma research, 2025 |
| Smaller models degrade faster and more steeply | ✓ | Chroma research, 2025 |
| Compressed context can outperform uncompressed on small models | ✓ | CompLLM, 2025 |
| U-shaped attention curve; middle of context loses 30%+ recall | ✓ | Liu et al., 2024 |
| Prompt caching ~90% cost reduction on stable prefixes | ✓ | Anthropic docs; LMCache analysis |
| Namespace unclaimed (SPORES, SEEDS, spore file conventions) | ✓ | No existing usage found |
| Workspace / module / component scope hierarchy | ✓ | Design intent; consistent with AGENTS.md standard |
| Task-specific spore files rather than monolithic SPORES.md | ✓ | Design intent |
| Select on precedent, compose on novelty | ✓ | Design intent |
| SEEDS.md at module root only, mutable | ✓ | Design intent |
| Token budget numbers per model class | ~ | Estimates; not empirically tested |
| 60-token ceiling per spore entry | ~ | Working hypothesis |
| Status lifecycle transition triggers | ~ | Partially specified |
| Commissioning skill implementation | ~ | Specified conceptually; not built |
| Hook validation approach | ~ | Unspecified |

---

## Companion documents needed

- `commissioning-skill/SKILL.md` — full specification of the commissioning skill
- `SEEDS_SPEC.md` — detailed format and lifecycle for SEEDS.md entries
- `HOOKS_GUIDE.md` — cchooks integration patterns for spore-compiled hooks
- Empirical token budget study — measure scion performance vs spore file size

---

*v0.2 — supersedes v0.1*
*Drafted 2026-03-20*
*Authors: human + Claude Sonnet 4.6*