# SEEDS.md
# module: singular-particular (workspace root)
# maintained-by: Claude Code (parent agent)
# last-updated: 2026-03-26

---
task-class: sorter
spore-file: spores/sorter-spores.md
status: provisional
deposited: 2026-03-24
supersedes: null
---

## Context

Files land in DumperCan/ from JL dropping content manually or from future
automation. They need to be classified by content type and routed to the
correct {section}/ToBuild/ subfolder. The sorter scion is Haiku-class —
fast, cheap, fully deterministic routing by file extension and filename
heuristics.

## Reasoning

Routing rules are deterministic enough to encode as spores: file extensions
map reliably to sections (.mp3/.flac → music, .jpg/.png/.webp → images, etc.).
Exception: .md files are inherently ambiguous - enforce file naming and yaml frontmatter conventions to assist future agents, scions and parents. 
Do not do with tokens what a tool or script can do for free. Empower your scions with a context saving toolkit that remains safe inside the folder the scion works within. 
Ambiguous files (no clear extension, mixed content) escalate to parent rather
than guessing wrong. DumperCan is the intake valve — routing errors here
propagate downstream, so conservative escalation is preferable to confident
misclassification.

A PostToolUse hook (dumpercan-watcher.py) fires when files are written to
DumperCan/ and triggers sorter scion commissioning automatically. JL does
not need to manually initiate sorting.

## Revision triggers

- New section added to the site (new routing destination needed)
- File naming conventions change and heuristics break
- Ambiguity rate too high (too many escalations) — tighten heuristics
- Ambiguity rate too low (wrong files silently misrouted) — loosen escalation

---
task-class: builder
spore-file: spores/builder-spores.md
status: provisional
deposited: 2026-03-24
supersedes: null
---

## Context

Files in {section}/ToBuild/ are ready to be built into HTML pages. The builder
scion is Gemini Flash, commissioned by Claude Code (parent). Claude Code tests
and refines Gemini's output before JL triggers deployment. The builder needs
section-specific context: what the aesthetic is, what the nav pattern is, what
external skills apply to the build type.

## Reasoning

Builder scions need more context than sorter scions — the aesthetic decisions
are non-trivial and the output must match the star-map visual language. The
commissioning skill should run skill-scout before commissioning a builder,
fetching the appropriate external skill (frontend-design for general pages,
annotated-writing for Writings section, etc.) and including it in the scion's
commission package.

Gemini Flash is the builder because of its 1M context window (useful for
holding multiple reference files simultaneously) and its strong frontend code
generation. Claude Code reviews output before commit — Gemini builds prototypes,
Claude refines them.

Output from builder scion goes to site/{section}/ not directly to Gitea.
Claude Code reviews, may iterate with another builder commission, then JL
triggers the commit when satisfied.

Files larger than 1MB referenced in built pages must use FileBrowser URLs,
not committed to git.

## Revision triggers

- Aesthetic decisions change project-wide (update spores + SEEDS.md)
- A new section type requires different build patterns
- Gemini replaced with a different builder model
- Skill-scout finds a better external skill for a build type

---
task-class: commit-tracker
spore-file: spores/commit-tracker-spores.md
status: provisional
deposited: 2026-03-24
supersedes: null
---

## Context

The commit-tracker is not a scion — it is a PostToolUse hook (commit-state-hook.py)
that fires when files in site/ are written or modified. It writes a state flag
spore entry to commit-tracker-spores.md indicating that changes exist but have
not been committed to Gitea. JL reads this to know when a commit is ready to
trigger. Parent agent reads this to know whether to proceed or wait.

This is a novel use of spores as state flags rather than policy decisions —
the first instance of this pattern in this project. The spore entry is mutable:
it is written when changes are detected and cleared (entry status set to
`committed`) when git confirms a successful push.

## Reasoning

The human-in-the-loop commit workflow (JL triggers commits) creates a state
ambiguity: neither the parent agent nor the builder scion knows whether their
output has been committed yet. The commit-tracker hook resolves this without
requiring JL to communicate the state manually. The parent reads
commit-tracker-spores.md before commissioning a new build to check whether
the previous build is safely committed.

The hook watches site/ writes only — DumperCan/ and ToBuild/ writes do not
trigger it (those are intermediate states, not committed outputs).

## Revision triggers

- Git workflow changes (automated commits reduce need for this tracker)
- Coolify deployment adds a webhook that confirms successful push (deprecate
  the hook in favor of the webhook signal)
- State flag pattern proves unreliable and a different mechanism is needed

---
task-class: designer
spore-file: spores/designer-spores.md
status: provisional
deposited: 2026-03-26
supersedes: null
---

## Context

The home page base architecture (site/index.html) is built and functional but
visually minimal — white dots on dark background, plain rectangles for skyline.
Two designer agents (Gemini Pro for visual design, Claude Sonnet for integration)
are commissioned to transform it into a rich post-apocalypse solarpunk-cyberpunk-
fantasy aesthetic. Designers work in CREATURE-PLAYGROUND/homepage-redesign/ and
produce draft HTML files. The parent (Opus) reviews and integrates to site/.

This is the first use of designer-class agents in this project — distinguished
from builder scions by operating at higher reasoning capacity and producing
design proposals rather than final builds.

## Reasoning

Designer agents need different policies than builder scions. Key distinctions:

**Output isolation**: designers write to CREATURE-PLAYGROUND/ not site/. This
prevents parallel work from colliding. The parent is the only agent that writes
to site/index.html — this is a merge point, not a race condition.

**Aesthetic enforcement**: Uncodixfy.md and the aesthetic brief must be loaded
at session start. These are the design guardrails. Without them, both Gemini
and Sonnet will default to generic AI aesthetics — the exact thing JL explicitly
does not want.

**Coordination protocol**: designers share a coordination.md file in the
playground. This is lighter than a full message-passing system and works because
both agents can read each other's drafts and leave status notes. The parent
resolves conflicts through coordination.md decisions table.

**Font and CSS constraints**: hard-coded in spores because these are absolute
rules (not contextual judgments). Border-radius 10px max, shadow blur 8px max,
banned font list — these never vary. Worth the token cost for the certainty.

**Defer-to-parent**: designers propose, parent decides. This prevents the
two designers from deadlocking on aesthetic disagreements.

## Revision triggers

- Designer agent models change (different token budgets needed)
- Project moves past home page to section pages (designers may need different
  output paths and coordination patterns)
- Aesthetic direction changes significantly (update aesthetic-brief.md and
  potentially spore policies)
- Coordination.md pattern proves inadequate (too many conflicts, need
  structured message passing instead)
