plugin-workflow

# 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:** 1. Load contracts in parallel (architecture.md, plan.md, parameter-spec.md, creative-brief.md) 2. Read Required Reading (juce8-critical-patterns.md) once at workflow start 3. Construct minimal prompt with plugin name + stage + Required Reading 4. Invoke subagent via Task tool 5. After subagent returns, invoke validation-agent (ALL stages 1-3) 6. 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](references/precondition-checks.md) for implementation. ## Resume Entry Point When resuming via `/continue [PluginName]`: 1. Verify state integrity (see references/state-management.md#verifyStateIntegrity) 2. Parse `.continue-here.md` for current stage and workflow mode 3. Verify contracts unchanged since last checkpoint (checksums match) 4. Verify git working directory clean 5. 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):** 1. Environment variables: `WORKFLOW_MODE=express|manual` 2. .continue-here.md field (for resumed workflows) 3. 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](references/workflow-mode.md) for implementation. ## Stage Dispatcher **Entry point:** Called by /implement or /continue after plugin-planning completes. **Dispatch flow:** 1. Verify state integrity → BLOCK if corrupted (exit 2 → run /reconcile) 2. Check preconditions → BLOCK if failed 3. **Automatic brief sync** (before Stage 1 only, if mockup exists) → See [references/creative-brief-sync.md](references/creative-brief-sync.md) 4. Route to subagent based on stage 5. Pass contracts and Required Reading to subagent 6. Wait for subagent completion 7. Invoke validation-agent with enhanced runtime validation 8. Execute checkpoint protocol See [references/dispatcher-pattern.md](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:** 1. Detect phases by scanning plan.md for phase markers 2. Loop through phases sequentially (Phase 2.1 → 2.2 → 2.3...) 3. Invoke subagent once per phase with phase-specific prompt 4. Run validation-agent after each phase 5. Execute checkpoint protocol after each phase 6. 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](references/phase-aware-dispatch.md) for detailed algorithm. ## Checkpoint Protocol After EVERY subagent return, execute this 6-step sequence: 1. **Verify state update:** Check subagent updated .continue-here.md and PLUGINS.md 2. **Fallback state update:** If verification fails, orchestrator updates state 3. **Invoke validation:** Run validation-agent for ALL stages 1-3 (BLOCKING on runtime failures) 4. **Commit stage:** Auto-commit all changes with git 5. **Verify checkpoint:** Validate all steps completed successfully 6. **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](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](references/validation-integration.md) for functions. ## Subagent Handoff Protocol Subagents update state files AND return JSON report: ```json { "status": "success" | "error", "stage": 1-3, "completionStatement": "...", "filesCreated": [...], "nextSteps": [...], "stateUpdated": true | false, "stateUpdateError": "..." (optional) } ``` **Verification:** 1. Check `stateUpdated` field in JSON report 2. If true: Verify .continue-here.md actually changed 3. If false/missing: Trigger orchestrator fallback **Fallback:** Orchestrator reads current state, updates fields, writes back. See [references/state-management.md](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:** 1. Read juce8-critical-patterns.md ONCE at workflow start 2. Prepend to all subagent prompts with clear separator 3. Pass to each subagent invocation from memory (no re-reading) ## Reference Files Each stage has detailed documentation in references/: - [stage-1-foundation-shell.md](references/stage-1-foundation-shell.md) - foundation-shell-agent prompt template - [stage-2-dsp.md](references/stage-2-dsp.md) - dsp-agent prompt template - [stage-3-gui.md](references/stage-3-gui.md) - gui-agent prompt template - [state-management.md](references/state-management.md) - State functions - [dispatcher-pattern.md](references/dispatcher-pattern.md) - Routing logic - [precondition-checks.md](references/precondition-checks.md) - Contract validation - [phase-aware-dispatch.md](references/phase-aware-dispatch.md) - Complex plugin handling - [workflow-mode.md](references/workflow-mode.md) - Express vs manual mode - [checkpoint-protocol.md](references/checkpoint-protocol.md) - 6-step checkpoint sequence - [validation-integration.md](references/validation-integration.md) - Validation-agent functions (enhanced runtime validation) - [creative-brief-sync.md](references/creative-brief-sync.md) - Automatic brief update from mockup - [error-handling.md](references/error-handling.md) - Error patterns and recovery - [integration-contracts.md](references/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: 1. Investigate (deep-research) 2. Show code 3. Show build output 4. 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](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