apecx-mcp-integration

The phased flow for any NON-TRIVIAL code change — plan → implement → self-review → critical review → commit with a Reviewed trailer. Use this whenever a change touches more than one code file, adds or edits logic/control-flow, introduces a new function/class/abstraction, or exceeds ~20 changed lines. It exists because "tests pass" is not "code is good": this skill forces the up-front plan and the critical review that momentum tends to skip, and ends at a commit the review gate will accept.

When and how to use the lightweight nanobrain authoring path (`nanobrain.lightweight.WorkflowBuilder` + auto-discovery) instead of hand-writing YAML or driving the apecx-mcp composer. Read whenever you need to prototype a workflow quickly, when you don't yet know the DAG shape, or when you want to programmatically generate YAML for many similar workflows.

How to author a Workflow YAML and (rarely) a Workflow subclass. Workflows are Steps that orchestrate other Steps via links. Covers the WorkflowConfig schema, step registration, link wiring, executor selection per step, DAG validation rules (cycle detection, orphan detection, self-referencing-link prohibition), execution model (event-driven vs. imperative), and the verbatim error messages from `workflow_graph.py`.

The event-driven contract — how DataUnits emit change events, how Triggers subscribe (or poll), and how Links transfer data from one step's output to another step's input. Read whenever you wire steps together, define triggers, or add a link. Covers all DataUnit subclasses (Memory/File/String/Stream/object-ref), all Trigger types (DataUnitChange/AllDataReceived/Timer/Manual), all Link types (Direct/Queue/Transform/Conditional/File/Academy), the AsyncTriggerExecutor's deadlock prevention, and the verbatim error messages.

Choosing and configuring an Executor (Local, Thread, Process, Parsl, GlobusCompute). Covers the async contract (`process()` must be async), executor-specific deadlock risks, the Parsl/HPC code path (Aurora PBS, ProxyStore, dynamic scaling), the Globus Compute remote-endpoint path (dispatch a step to Aurora via Globus Compute + Globus Auth), per-step `executor_config:` binding, and verbatim error messages. Read whenever you set or change a step's `executor:` field, especially before declaring distributed execution "working".

How to write YAML configuration files for nanobrain components. Covers the `class:` + `config:` pattern for nested references, environment variable interpolation, the file-path resolution order, the difference between `ConfigBase` (file-only) and inline-dict-tolerant configs (DataUnit/Link/Trigger), and the standard fields shared across all components. Read this whenever you create or edit a `*.yml` under a nanobrain project.

How to create nanobrain components correctly via the mandatory `from_config` pattern. Read this FIRST before authoring any nanobrain code (steps, workflows, agents, tools, data units, links, triggers, executors). Covers the call sequence inside `from_config()`, configuration file path resolution, the four supported input shapes (str/Path/dict/Pydantic), the `class:` auto-delegation trick, the `_allow_direct_instantiation` backdoor, and the verbatim error messages the framework raises on violations.

How to write tests for nanobrain components without mocking the framework into uselessness, and how to debug the framework's most common failure modes (FAIL-FAST at init, silent never-fires-trigger, link reference typos, Parsl worker import errors). Read whenever you author or fix a test, or when a step/workflow refuses to run.

How to author Agents and Tools in nanobrain, including LLM model selection, system-prompt-in-YAML rule, Tool subclassing (`async def execute`), tool registration via config (NOT programmatic), the A2A (Agent-to-Agent) protocol surface, and the MCP (Model Context Protocol) client integration. Read whenever you create an Agent, a Tool, or an external-system integration.

How to author a `BaseStep` (or `Step`) subclass correctly. Covers the execute/process/_execute_process triad (you implement `process`, never override `execute`), the data-unit and trigger ownership boundary, the StepConfig schema, the FAIL-FAST validations the framework runs at step initialization, and the verbatim error messages that signal each violation. Read this whenever you create a new step class or modify an existing one.