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

---
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.

---
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