plugin-workflow Skill

Purpose: Pure orchestrator for stages 1-3 of JUCE plugin implementation with automatic validation after each stage. This skill delegates to specialized subagents and validation-agent for continuous quality assurance.

Overview

Implementation milestones:

• Build System Ready (Stage 1): Create build system and implement parameters (foundation-shell-agent)

• Audio Engine Working (Stage 2): Implement audio processing (dsp-agent)

• UI Integrated (Stage 3): Connect WebView interface to audio engine (gui-agent)

Stage 0 (Research & Planning) is handled by plugin-planning skill.

After Stage 3 completes, plugin is ready for installation (no separate validation stage - validation is automatic and continuous).

Delegation Protocol

CRITICAL: Stages 1-3 MUST invoke subagents via Task tool. This skill is a pure orchestrator and NEVER implements plugin code directly.

Delegation sequence for every stage:

• Load contracts in parallel (architecture.md, plan.md, parameter-spec.md, creative-brief.md)

• Read Required Reading (juce8-critical-patterns.md) once at workflow start

• Construct minimal prompt with plugin name + stage + Required Reading

• Invoke subagent via Task tool

• After subagent returns, invoke validation-agent (ALL stages 1-3)

• Execute checkpoint protocol (see references/checkpoint-protocol.md)

Stage routing:

• Stage 1 → foundation-shell-agent

• Stage 2 → dsp-agent

• Stage 3 → gui-agent

Validation routing: After each stage completes, validation-agent runs automatically with enhanced runtime validation (compile-time + runtime tests). If validation fails with continue_to_next_stage: false , workflow BLOCKS until issues resolved.

Preconditions

Before starting Stage 1, verify these contract files exist:

• plugins/$PLUGIN_NAME/.ideas/architecture.md (from Stage 0)

• plugins/$PLUGIN_NAME/.ideas/plan.md (from Stage 0)

• plugins/$PLUGIN_NAME/.ideas/creative-brief.md (from ideation)

• plugins/$PLUGIN_NAME/.ideas/parameter-spec.md (from UI mockup finalization)

If parameter-spec-draft.md exists but parameter-spec.md missing: Block with message: "Draft parameters found, but full specification required. Complete UI mockup workflow to generate parameter-spec.md. Run: /dream [PluginName] → option 2 (Full UI mockup first)"

If contracts missing: Block and instruct user to run /plan [PluginName] to complete Stage 0.

See references/precondition-checks.md for implementation.

Resume Entry Point

When resuming via /continue [PluginName] :

• Verify state integrity (see references/state-management.md#verifyStateIntegrity)

• Parse .continue-here.md for current stage and workflow mode

• Verify contracts unchanged since last checkpoint (checksums match)

• Verify git working directory clean

• Verify PLUGINS.md status matches .continue-here.md stage

If all checks pass: Resume at stage specified in .continue-here.md If any fail: Present recovery menu (reconcile / clean working directory / review changes)

Workflow Mode

Determine whether to auto-progress (express mode) or present menus (manual mode).

Mode sources (priority order):

• Environment variables: WORKFLOW_MODE=express|manual

• .continue-here.md field (for resumed workflows)

• Default to "manual"

Express mode behavior:

• Auto-progress through stages without menus

• Drops to manual on ANY error (build failures, validation failures, etc.)

• Final menu always appears after Stage 3 (plugin complete)

See references/workflow-mode.md for implementation.

Stage Dispatcher

Entry point: Called by /implement or /continue after plugin-planning completes.

Dispatch flow:

• Verify state integrity → BLOCK if corrupted (exit 2 → run /reconcile)

• Check preconditions → BLOCK if failed

• Automatic brief sync (before Stage 1 only, if mockup exists) → See references/creative-brief-sync.md

• Route to subagent based on stage

• Pass contracts and Required Reading to subagent

• Wait for subagent completion

• Invoke validation-agent with enhanced runtime validation

• Execute checkpoint protocol

See references/dispatcher-pattern.md for full algorithm.

Phase-Aware Dispatch

For Stages 2-3 with complexity ≥3, use phase-aware dispatch to incrementally implement complex plugins.

When to use:

• Stage 2 (DSP) or Stage 3 (GUI)

• Complexity score ≥3 (from plan.md)

• plan.md contains phase markers (### Phase 2.X or ### Phase 3.X)

How it works:

• Detect phases by scanning plan.md for phase markers

• Loop through phases sequentially (Phase 2.1 → 2.2 → 2.3...)

• Invoke subagent once per phase with phase-specific prompt

• Run validation-agent after each phase

• Execute checkpoint protocol after each phase

• Present decision menu showing progress ("Phase 2 of 4 complete")

CRITICAL: Never send "Implement ALL phases" to subagent. This caused DrumRoulette Stage 2 compilation errors. Phase-aware dispatch is MANDATORY for complex plugins.

See references/phase-aware-dispatch.md for detailed algorithm.

Checkpoint Protocol

After EVERY subagent return, execute this 6-step sequence:

• Verify state update: Check subagent updated .continue-here.md and PLUGINS.md

• Fallback state update: If verification fails, orchestrator updates state

• Invoke validation: Run validation-agent for ALL stages 1-3 (BLOCKING on runtime failures)

• Commit stage: Auto-commit all changes with git

• Verify checkpoint: Validate all steps completed successfully

• Handle checkpoint: Present menu (manual mode) or auto-progress (express mode)

Checkpoint applies to:

• Simple plugins (complexity ≤2): After stages 1, 2, 3

• Complex plugins (complexity ≥3): After stage 1 AND after EACH DSP/GUI phase (2.X, 3.X)

See references/checkpoint-protocol.md for implementation.

Validation Integration

Stages 1-3 invoke validation-agent with enhanced runtime validation after subagent completes:

• BLOCKING on runtime failures: If status: FAIL and continue_to_next_stage: false , workflow stops

• Runs compile-time checks (contract matching, implementation correctness)

• Runs runtime tests (load plugin, process audio, parameter changes) when binary available

• Returns JSON report with status, checks, recommendation

• Max 500 tokens per report

Blocking behavior:

• If validation passes (PASS/WARNING): Continue to next stage

• If validation fails with continue_to_next_stage: true : Present warning, allow continuation

• If validation fails with continue_to_next_stage: false : BLOCK workflow, present error menu

See references/validation-integration.md for functions.

Subagent Handoff Protocol

Subagents update state files AND return JSON report:

{ "status": "success" | "error", "stage": 1-3, "completionStatement": "...", "filesCreated": [...], "nextSteps": [...], "stateUpdated": true | false, "stateUpdateError": "..." (optional) }

Verification:

• Check stateUpdated field in JSON report

• If true: Verify .continue-here.md actually changed

• If false/missing: Trigger orchestrator fallback

Fallback: Orchestrator reads current state, updates fields, writes back.

See references/state-management.md for fallback implementation.

Required Reading Injection

All subagents (stages 1-3) receive troubleshooting/patterns/juce8-critical-patterns.md to prevent repeat mistakes.

Implementation:

• Read juce8-critical-patterns.md ONCE at workflow start

• Prepend to all subagent prompts with clear separator

• Pass to each subagent invocation from memory (no re-reading)

Reference Files

Each stage has detailed documentation in references/:

• stage-1-foundation-shell.md - foundation-shell-agent prompt template

• stage-2-dsp.md - dsp-agent prompt template

• stage-3-gui.md - gui-agent prompt template

• state-management.md - State functions

• dispatcher-pattern.md - Routing logic

• precondition-checks.md - Contract validation

• phase-aware-dispatch.md - Complex plugin handling

• workflow-mode.md - Express vs manual mode

• checkpoint-protocol.md - 6-step checkpoint sequence

• validation-integration.md - Validation-agent functions (enhanced runtime validation)

• creative-brief-sync.md - Automatic brief update from mockup

• error-handling.md - Error patterns and recovery

• integration-contracts.md - Component contracts

Integration Points

Invoked by:

• /implement command (after plugin-planning completes)

• /continue command (for stages 1-3)

• context-resume skill (when resuming implementation)

Invokes via Task tool:

• foundation-shell-agent (Stage 1) - REQUIRED

• dsp-agent (Stage 2) - REQUIRED

• gui-agent (Stage 3) - REQUIRED

• validation-agent (Stages 1-3) - REQUIRED, BLOCKING on runtime failures

Also invokes:

• build-automation skill (build verification)

• plugin-lifecycle skill (if user chooses to install)

Reads (contracts):

• architecture.md, plan.md, creative-brief.md, parameter-spec.md

Creates:

• .continue-here.md (handoff file)

Updates:

• PLUGINS.md (status after each stage)

• .continue-here.md (after each stage)

Deletes after Stage 3:

• .continue-here.md (workflow complete, plugin ready for installation)

Error Handling

Contract files missing before Stage 1: Block and instruct user to run /plan [PluginName] .

Build fails during subagent execution: Subagent returns error. Present menu:

• Investigate (deep-research)

• Show code

• Show build output

• Manual fix (resume with /continue)

State mismatch detected (exit 2): BLOCKING error - user must run /reconcile [PluginName] to fix.

Validation fails with continue_to_next_stage: false: BLOCKING error. Present menu with investigation options. Workflow cannot proceed until issues resolved.

Validation fails with continue_to_next_stage: true: Present warning, allow user to decide whether to continue or fix issues first.

See references/error-handling.md for detailed patterns.

Decision Menu Protocol

Use inline numbered menus for:

• After EVERY stage completion (checkpoint gates)

• Build failure recovery

• Test failure investigation

• Phase completion (for complex plugins)

Format:

✓ [Milestone name]

What's next?

1. [Next milestone action] (recommended)
2. [Run tests] - Verify implementation
3. [Pause workflow] - Resume anytime
4. [Review code] - See what was implemented
5. Other

Choose (1-5): _

Express mode: Skip menus and auto-progress to next stage (except final stage). Manual mode: ALWAYS wait for user response.

Success Criteria

Workflow succeeds when:

• All subagents (stages 1-3) invoked successfully via Task tool

• Plugin compiles without errors at each stage

• All validation passes (or explicitly allowed to continue with warnings)

• All stages completed in sequence (1 → 2 → 3)

• Decision menus presented after EVERY stage (manual mode)

• PLUGINS.md updated to ✅ Working after Stage 3

• Handoff file deleted after Stage 3 (workflow complete)

• Git history shows atomic commits for each stage

Anti-Patterns

Common pitfalls to AVOID:

CRITICAL:

• ❌ Implementing stage logic directly in orchestrator

• ✓ ALWAYS use Task tool to invoke appropriate subagent

CRITICAL:

• ❌ Sending "Implement ALL phases" to subagent for Stages 2-3

• ✓ ALWAYS detect phases in plan.md and loop through them one at a time

CRITICAL:

• ❌ Proceeding to next stage when validation fails with continue_to_next_stage: false

• ✓ BLOCK workflow and present error menu until issues resolved

HIGH:

• ❌ Not verifying subagent updated state

• ✓ Check stateUpdated field, verify .continue-here.md changed, fallback if needed

HIGH:

• ❌ Skipping phase detection for Stages 2-3 when complexity ≥3

• ✓ Read plan.md to check for phases BEFORE invoking dsp-agent or gui-agent

HIGH:

• ❌ Skipping validation after subagent completes

• ✓ ALWAYS invoke validation-agent after each stage (1-3)

MEDIUM:

• ❌ Not injecting Required Reading to subagents

• ✓ Always pass juce8-critical-patterns.md to prevent repeat mistakes