Amazing PsyCoder — System Orchestrator
Version
v1.2 — stable, 2026-06-06.
Purpose
This is the single entry point for the Amazing PsyCoder experimental skill system. It orchestrates a mandatory sequential chain of three sub-skills that convert psychological experiment ideas into audited, production-quality code.
This skill does NOT generate code itself. It routes the user through the correct sequence and enforces the chain: Programming → Coder → Reviewer. No step may be skipped.
Platforms: Claude Code / Codex / Hermes / OpenClaw — follows the agentskills.io open standard. See PLATFORMS.md for platform-specific installation and tool mapping.
System Architecture
User describes experiment (English / 中文)
│
▼
┌──────────────────────────────────────┐
│ ① psych-experiment-programming │ Orchestration layer
│ Input: natural language description│ 5-phase design workflow
│ Output: config YAML + conditions │ Design Decision Registry
│ Gates: Gate 1→2→3→4→5 │ Progressive confirmation
└──────────────┬───────────────────────┘
│ config YAML (internal artifact, not shown to user)
▼
┌──────────────────────────────────────┐
│ ② psych-experiment-coder │ Code generation layer
│ Input: config YAML + conditions │ 12-step code template
│ Output: runnable code + README │ 4-layer priority architecture
│ Gate: 9-item post-generation check │ Canonical Code Skeleton
└──────────────┬───────────────────────┘
│ Runnable experiment code
▼
┌──────────────────────────────────────┐
│ ③ psych-experiment-code-reviewer │ Audit layer (final mandatory gate)
│ Input: code / config / plan │ 5 review modes
│ Output: audit report + readiness │ Platform-aware checks
│ Gate: 0 Critical + 0 Major │ Severity grading
└──────────────────────────────────────┘
> All three steps are mandatory — none can be skipped. Programming → Coder → Reviewer. No experiment code is considered complete without passing reviewer audit with ready_for_collection or ready_after_minor_fixes.
How to Use This Skill
When a user invokes this skill, determine where they are in the pipeline and route accordingly:
Routing Decision Tree
User request
│
├─ "I want to build an experiment" / "我要做一个…实验"
│ → Invoke psych-experiment-programming (start Phase 1)
│
├─ "Generate code for this config" / "生成代码"
│ → Check: has Programming Gate 5 passed?
│ Yes → Invoke psych-experiment-coder
│ No → Route back to psych-experiment-programming first
│
├─ "Review this experiment code" / "审计这个实验"
│ → Invoke psych-experiment-code-reviewer
│
├─ "I got an error" / "代码报错"
│ → Check the error type:
│ Design error → psych-experiment-programming
│ Code error → psych-experiment-coder (see Debugging & Iteration Loop)
│
├─ "Review found issues" / "审计不通过" / "代码有问题需要修"
│ → Check the severity:
│ Critical/Major issues → Fix in psych-experiment-coder, re-audit after
│ Minor only → User can collect data; fix when convenient
│
├─ "What paradigms are available?" / "有哪些范式"
│ → Show [Paradigm Coverage Matrix](#paradigm-coverage-matrix)
│
└─ "How does this system work?" / "这个系统怎么用"
→ Show system overview + three-step chain
Mandatory Execution Order
- First: Invoke
psych-experiment-programming— guide user through 5-phase design. Output: complete config YAML (internal, not shown to user) - Second: Invoke
psych-experiment-coder— generate platform code from config. Output:.py/.js/.m+ README - Third: Invoke
psych-experiment-code-reviewer— audit the generated code. Output: audit report + readiness label
Never skip a step. Never generate code before the trial window timeline is confirmed.
Design Principles (System-Wide)
| # | Principle | Description | Applies to |
|---|---|---|---|
| 1 | Output is deliverable | Every phase produces complete, usable artifacts | All |
| 2 | Progressive confirmation | Design decisions confirmed phase by phase; defaults flagged [ASSUMED] |
Programming |
| 3 | Decision traceability | Design Decision Registry records source of every decision | Programming |
| 4 | Skeleton-first generation | All code generation MUST start from platform spec Canonical Code Skeleton | Coder |
| 5 | Paradigms provide logic, skeleton provides API | Paradigm files define experiment logic; API patterns from spec skeleton | Coder |
| 6 | Anti-pattern zero-tolerance | time.sleep(), event.getKeys(maxWait=), KbCheck for RT, jsPsych.init(), WaitSecs — blocked |
Coder, Reviewer |
| 7 | Your experiment, our standards | User owns the experimental design; system guarantees code quality | All |
| 8 | Window timeline before code | No code generation before trial window timeline is validated | Programming, Coder |
| 9 | Post-generation audit mandatory | All generated code must pass through Reviewer before data collection | Coder, Reviewer |
| 10 | Input bounds output | Reviewer's conclusions cannot exceed what the input supports | Reviewer |
Red Lines (System-Wide Absolute Prohibitions)
These rules span all three skills. Violation is never acceptable:
| # | Rule | Owned by | Consequence of violation |
|---|---|---|---|
| R1 | No code generation before trial window timeline is complete | Programming | Structural errors, expensive late-stage fixes |
| R2 | No assumed response mapping | Programming | Guessing key mapping invalidates accuracy data |
| R3 | No time.sleep() in experiment code |
Coder | Blocks event loop, Escape unresponsive |
| R4 | No event.getKeys(maxWait=...) |
Coder | Blocks event loop |
| R5 | No data saved only at experiment end | Coder | Crash = all data lost |
| R6 | No silent filling of [MISSING] values |
Programming | Every gap must be resolved by asking user or offering flagged default |
| R7 | No Chinese/CJK text without explicit font | Coder | PsychoPy default font lacks CJK glyphs; text renders as tofu (□□□) |
| R8 | No skipping paradigm Must-Confirm items | Programming | Unconfirmed items produce broken experiments |
| R9 | No rt_onset omitted on response windows |
Coder | Missing/incorrect RT onset invalidates all reaction time data |
| R10 | No code delivery without Reviewer pass | All | All code must pass reviewer audit before data collection |
Code Generation Architecture (4-Layer Priority)
All platforms use the same 4-layer priority stack. When layers conflict, higher always wins:
Layer 1: spec/ ← Highest: API spec, anti-patterns, Canonical Code Skeleton
Layer 2: mapping/ ← Structural: config YAML fields → platform code structures
Layer 3: paradigms/ ← Paradigm logic: window sequence, accuracy rules, condition structure
Layer 4: demo/ ← Lowest: raw demo code, logic reference only, never API reference
Code generation priority: spec canonical skeleton > spec anti-patterns > config→code mapping > paradigm logic > demos
Platform Layer Fill Status
| Layer | PsychoPy | jsPsych | Psychtoolbox |
|---|---|---|---|
L1 spec/ |
✅ | ✅ | ✅ |
L2 mapping/ |
✅ | ✅ | ✅ |
L3 paradigms/ |
✅ 27 paradigms | ✅ 25 paradigms | ✅ 5 paradigms |
L4 demo/_raw/ |
✅ 45 .py |
✅ 23 .js |
✅ 100 .md |
Code Template (Overview)
All generated code follows a 12-step structure: imports → parameters → display setup → stimulus preloading → condition loading → helpers → instructions → practice → main loop (blocks → randomization → per-trial windows) → incremental data save → cleanup → package with README. The full template with detailed per-step requirements is in the coder SKILL.md.
Post-Generation Quality Gate (Overview)
Before delivery, all generated code must pass the 9-item Quality Gate defined in the coder SKILL.md. Covers: spec skeleton compliance, anti-pattern scan, API patterns, parameter placement, escape handling, RT source, incremental save, preloading, and CJK font config. Any failure = fix before delivery.
Review Modes and Readiness Labels
Review Modes (auto-selected by Reviewer)
| Mode | Input | Maximum label |
|---|---|---|
code-audit |
Complete experiment code | ready_for_collection |
config-audit |
Config YAML / trial timeline | pre_code_ready |
implementation-plan-review |
Pseudocode / architecture plan | pre_code_ready |
triage-only |
Natural-language description | None (missing-info list only) |
blocked |
Insufficient input | None (state what's needed) |
Readiness Labels
| Label | Meaning |
|---|---|
ready_for_collection |
Zero Critical + zero Major — can collect data |
ready_after_minor_fixes |
Only Minor issues remain |
not_ready_for_collection |
Critical or Major issues exist — do NOT collect |
pre_code_ready |
Design complete, ready for code generation |
needs_experiment_info |
Key design information missing |
blocked |
Input insufficient for any review |
Severity Classification
| Severity | Definition | Can collect data? |
|---|---|---|
| Critical | Invalidates all data; must fix before any collection | No |
| Major | Degrades data quality; fix before formal collection | No |
| Minor | Does not affect data quality; fix when convenient | Yes |
Paradigm Coverage Matrix
Core Paradigms (14) — Full Programming-Layer Spec
All 10 required sections filled (When to Use, Core Logic, Must Confirm, Do Not Assume, Condition File Columns, Trial Window Timeline, Data Output Columns, Randomization Checks, Common Failure Modes, Example):
Go/No-go · Navon · Priming · Stroop · Eriksen Flanker · Simon · Rating · Stop-signal · IAT · N-back · Dot-probe · Visual Search · Task Switching · EAST
Extended Paradigms (24) — Programming-Layer Reference Descriptions
Antisaccade · ANT · BART · Bilingual Stroop · Change Detection · Children Flanker · Choice RT · Climate Reflection · CPT · Corsi Blocks · Cyberball · Delay Discounting · Drag and Drop · Mental Rotation · Multisensory Nature · Numerical Stroop · Phone a Friend · Posner Cuing · Psychophysics Staircase · Rating to Choice · Sternberg · Ultimatum Game · WCST · Writing Distraction
Paradigm Count Explained
| Layer | Count | What they are |
|---|---|---|
| Programming paradigms/ | 38 (14 core + 24 extended) | Design references for the 5-phase workflow. Apply to ALL platforms |
| Coder psychopy/paradigms/ | 27 | PsychoPy code references with platform-specific generation logic |
| Coder jspsych/paradigms/ | 25 | jsPsych code references with timeline plugins |
| Coder psychtoolbox/paradigms/ | 5 | PTB code references; most paradigms use 12-step template for manual adaptation |
Cross-Platform Mandatory API Quick Reference
| Dimension | PsychoPy | jsPsych (7.x) | Psychtoolbox |
|---|---|---|---|
| Keyboard | keyboard.Keyboard(backend='ptb') |
Plugin class references | KbQueueCreate + KbQueueCheck |
| RT source | key.rt (USB HID async) |
data.rt (automatic) |
firstPress - VBLTimestamp |
| RT origin | win.callOnFlip(kb.clock.reset) |
Stimulus onset (automatic) | VBLTimestamp = Screen('Flip') return |
| Timing loop | CountdownTimer |
trial_duration parameter |
vbl + (waitframes-0.5)*ifi |
| Data save | try/finally + per-trial flush |
on_finish callback |
try/catch + fopen/fprintf/fclose |
| Quit | Escape check in every loop | 'escape' in choices |
KbCheck(KbName('ESCAPE')) |
| Cleanup | win.close() + core.quit() |
jsPsych.endCurrentTimeline() |
sca + Priority(0) + ShowCursor |
| CJK font | FONT_CONFIG toggle + TextBox2 |
CSS font-family |
Screen('TextFont') + TextStyle |
Inter-Skill Communication Protocol
Programming → Coder
- Artifact: Complete
config.yaml(internal, never shown to user) - Precondition: Gate 5 passed (user confirmed full Design Decision Registry)
- Coder's duty: Load config → select platform → copy skeleton → map code → Quality Gate → deliver
Coder → Reviewer
- Artifact: Generated experiment code (
.py/.js/.m) + condition files + README - Precondition: Coder's Post-Generation Quality Gate passed
- Reviewer's duty: Detect platform → load corresponding spec → audit each dimension → output graded report + readiness label
Shared Artifacts
| Artifact | Producer | Consumer | Format |
|---|---|---|---|
| config YAML | Programming | Coder | .yaml (internal, not displayed) |
| Condition files | Programming | Coder | .xlsx / .csv |
| Experiment code | Coder | Reviewer, User | .py / .js / .m |
| Experiment README | Coder | Reviewer, User | .md (alongside code) |
| Audit report | Reviewer | User | Markdown (graded + readiness label) |
Code Output Specification
Deliverables
Every code generation produces two files:
| File | Format | Content |
|---|---|---|
| Platform experiment file | .py / .js / .m |
Runnable code, all parameters at top, FONT_CONFIG toggle if CJK used |
| Experiment README | .md |
Window sequence diagram, condition/block structure, response rules, data columns, how to run, parameter line numbers, known limitations |
Language Consistency
Code comments and README language MUST match the user's language:
- 中文用户 → 中文 README + 中文代码注释
- English user → English README + English code comments
File Structure
amazing-psycoder-skills/
├── amazing-psycoder/ ← Entry orchestrator (this skill)
│ ├── SKILL.md
│ ├── PLATFORMS.md ← Platform adapter reference
│ ├── install.sh ← Cross-platform installer
│ ├── psych-experiment-programming/ ← ① Orchestration layer
│ │ ├── SKILL.md ← 5-phase workflow + 10 red lines
│ │ ├── README.md
│ │ ├── paradigms/ ← 38 paradigm reference files
│ │ └── references/ ← Design references (config-schema, timing, etc.)
│ ├── psych-experiment-coder/ ← ② Code generation layer
│ │ ├── SKILL.md ← Generation flow + 4-layer arch + 9-item gate
│ │ ├── README.md
│ │ ├── psychopy/ ← PsychoPy (full auto)
│ │ │ ├── spec/README.md ← Canonical Skeleton + anti-patterns
│ │ │ ├── mapping/README.md ← Config→code mapping
│ │ │ ├── paradigms/ ← 27 paradigm references
│ │ │ └── demo/_raw/ ← 45 demo .py files
│ │ ├── jspsych/ ← jsPsych
│ │ │ ├── spec/README.md ← Canonical Skeleton + anti-patterns
│ │ │ ├── mapping/README.md ← Config→timeline + migration table
│ │ │ ├── paradigms/ ← 25 paradigm references
│ │ │ └── demo/_raw/ ← 23 demo .js files
│ │ └── psychtoolbox/ ← PTB
│ │ ├── spec/README.md ← Canonical Skeleton + anti-patterns
│ │ ├── mapping/README.md ← Config→MATLAB + frame loops
│ │ ├── paradigms/ ← 5 paradigm references
│ │ └── demo/_raw/ ← 100 API demos by category
│ └── psych-experiment-code-reviewer/ ← ③ Audit layer
│ ├── SKILL.md ← 5 review modes + platform-aware audit
│ └── README.md
├── docs/ ← Multi-language READMEs
│ ├── README_EN.md
│ ├── README_ZH-HANT.md
│ ├── README_JA.md
│ ├── README_DE.md
│ └── README_FR.md
└── README.md ← Main README (简体中文)
When NOT to Use This Skill
- Quick PsychoPy/jsPsych/PTB API questions: Answer directly; don't invoke the full workflow
- General Python/JavaScript/MATLAB questions: Answer directly
- Non-experiment programming tasks: Not in scope
