cl1-base

name	cl1-base
description	Build or adapt baseline CL1 human-neuron models, stimulation loops, and evaluation workflows. Use when Codex needs to design or modify CL1 training code, UDP stimulation and spike protocols, safe stimulation ranges, Same Frame Encoding (SFE), ablations, feedback-channel logic, or hardware-aware data and training loops for CL1 systems.

CL1 Base

Use this skill to preserve CL1-specific invariants while changing the task, model family, or dataset.

Workflow

1. Read references/cl1-udp-protocol.md before changing network transport, channel layout, or stimulation bounds.
2. Read references/cl1-model-patterns.md before changing the stim policy, readout head, feedback design, or training loop.
3. Use scripts/cl1_udp_training_scaffold.py when a new project needs a minimal CL1-compatible UDP client, channel mapper, rest-cycle guard, and training-loop hook points.
4. Use scripts/cl1_stim_safety_validator.py to validate amplitudes, pulse widths, charge, and channel IDs before sending near-limit settings.
5. Use scripts/cl1_channel_layout_helper.py to draft channel-role allocations while preserving the dead-channel mask.
6. Read references/cl1-operations-patterns.md before changing recording flow, event signaling, feedback routing, startup order, or observability.
7. Use scripts/cl1_multiport_protocol_helper.py when a project needs separate stim, spike, feedback, and event schemas.
8. Use scripts/cl1_feedback_scaling_helper.py when feedback needs direct reward scaling, EMA surprise scaling, or value-error scaling.
9. Use scripts/cl1_transport_self_test.py to round-trip packet schemas and catch sender/receiver mismatches early.
10. If anything about CL1 handling is unclear, check the official Cortical Labs docs first: https://docs.corticallabs.com/.
11. Preserve the hardware and training guardrails unless the user explicitly asks to re-validate them experimentally.

Non-Negotiables

• Keep stimulation arrays at 64 channels and treat [0, 4, 7, 56, 63] as dead channels.
• Treat the official CL API limits as hard bounds unless Cortical Labs provides newer guidance:
  • amplitude: (0.0, 3.0] uA
  • pulse width: (0, 10000] us in 20 us steps
  • total charge per stim pulse: <= 3 nC
• If using UDP or another network bridge, keep the transport schema explicit and keep the training side and device side aligned.
• Keep artifact rejection and spike collection timing explicit. A strong starting point is a 50 ms wait before accepting spikes and a 5 s UDP timeout on the training side.
• Treat amp=0 as silent. Validation may skip range checks for silent channels.
• Keep training serial at batch_size=1 while using live CL1 stimulation.
• Use conservative operating defaults unless the task explicitly needs higher values. A cautious starting point is lower than the documented hard limits.
• If an implementation approaches the upper end of amplitude, pulse width, frequency, or charge, re-check the current official Cortical Labs docs before proceeding, then validate against the current documented limits and surface the risk to the user.

Default Modeling Pattern

• Split the problem into a stim policy and a spike-conditioned readout head or task head.
• Use REINFORCE or another gradient-free policy update on the stim side when the biological bottleneck is non-differentiable.
• Treat SFE as an optional pattern for exposing the same input through multiple encodings or views when richer stimulation structure may help.
• Start from a readout head that is intentionally capacity-limited, then compare against the ablation baseline before increasing capacity.
• Do not hand the readout head easy shortcuts unless the user explicitly wants that tradeoff.

Evaluation Rules

• Run an ablation that removes real spike information before trusting any downstream metric.
• Interpret small metric gains cautiously; the readout head can learn task shortcuts without using spikes.
• Keep clip boundaries explicit, preserve intra-clip order, and insert pause/rest logic so the cells are not trained as if they were a normal simulator.

Collaboration Rules

• When stuck, ask a clarifying question or propose a short plan.
• Do not push large speculative changes without confirmation.
• Before stopping, review the implementation and check for a better or simpler approach.
• Before stopping, remove redundant code, duplicate logic, and dead or unused code when found.
• If the implementation is already clean, state that briefly.

Resources

• references/cl1-udp-protocol.md: packet layout, channel map, safe ranges, and device timing.
• references/cl1-model-patterns.md: SFE, feedback policy, decoder ablation logic, and non-obvious training heuristics.
• references/cl1-operations-patterns.md: multi-port transport, event signaling, recording lifecycle, startup order, observability, and caching patterns.
• scripts/cl1_udp_training_scaffold.py: reusable scaffold for UDP-connected CL1 training loops.
• scripts/cl1_stim_safety_validator.py: standalone safety and near-limit validator for amplitudes, pulse widths, charge, and channel IDs.
• scripts/cl1_channel_layout_helper.py: channel-role allocation helper for learned stim and feedback partitions.
• scripts/cl1_multiport_protocol_helper.py: stim/spike/event/feedback packet helpers for multi-port CL1 systems.
• scripts/cl1_feedback_scaling_helper.py: reusable reward and surprise scaling helpers for CL1 feedback.
• scripts/cl1_transport_self_test.py: packet schema round-trip tests for transport validation.
• scripts/cl1_stim_cache.py: lightweight LRU cache for stimulation design reuse and cleanup.