Amazing PsyCoder

Workflows

Orchestrates psychological experiment creation by enforcing a 3-step chain: design via 5-phase programming, code generation, and mandatory code review for Ps...

Install

openclaw skills install amazing-psycoder

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